Integrate Login and Authentication

Before you start

Make sure your RiskOS™ environment is provisioned with:

• A workflow configured for the Login and Authentication solution.
• Verified global support coverage for the Login and Authentication solution.

Choose your environment

Start with Sandbox for development and testing, then move to Production for live applications.

https://riskos.sandbox.socure.com/api/evaluation

• No real customer data
• Free testing environment
• Unlimited API calls

https://riskos.socure.com/api/evaluation

• Real customer data
• API usage charges apply
• Connects to live data services

Get an API key

1. In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.

2. Copy your API key securely.

3. In the Production RiskOS™ Dashboard, go to Developer Workbench > API Keys.

4. Copy your API key securely.

How it works

1. Send a POST /api/evaluation request with login event, identity, and device data.
2. RiskOS™ evaluates the request using your Login and Authentication workflow.
3. You receive a decision (APPROVE, REVIEW, or REJECT).
4. Apply the decision to allow access, require step-up verification, or block the login attempt.

📘
Note:
The decision values shown in this guide (APPROVE, REVIEW, REJECT) reflect a customized Login and Authentication workflow. Your environment may use different default decision values depending on how your workflow is configured.

Start a new evaluation

Endpoint

Sandbox
Production

POST https://riskos.sandbox.socure.com/api/evaluation

POST https://riskos.socure.com/api/evaluation

Authentication and headers

Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

Example request: application/json required

{
  "id": "ato-78901",
  "timestamp": "2023-12-01T15:45:12.678Z",
  "workflow": "account_takeover",
  "data": {
    "event_type": "address_update",
    "event_category": "update",
    "ip_address": "203.0.113.10",
    "individual": {
      "id": "ind-9876543",
      "given_name": "Jane",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1990-05-15",
      "email": "jane.smith@example.com",
      "phone_number": "+1-312-555-1234",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s"
    },
    "event_details": {
      "previous": {
        "address": {
          "line_1": "123 Main Street",
          "line_2": "Suite 100",
          "locality": "Brooklyn",
          "major_admin_division": "NY",
          "country": "US",
          "postal_code": "11201"
        }
      }
    },
    "custom": {}
  }
}

curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{\n  "id": "ato-78901",\n  "timestamp": "2023-12-01T15:45:12.678Z",\n  "workflow": "account_takeover",\n  "data": {\n    "event_type": "address_update",\n    "event_category": "update",\n    "ip_address": "203.0.113.10",\n    "individual": {\n      "id": "ind-9876543",\n      "given_name": "Jane",\n      "family_name": "Smith",\n      "national_id": "123456789",\n      "date_of_birth": "1990-05-15",\n      "email": "jane.smith@example.com",\n      "phone_number": "+1-312-555-1234",\n      "address": {\n        "line_1": "742 Evergreen Terrace",\n        "line_2": "Apt 12B",\n        "locality": "Springfield",\n        "major_admin_division": "IL",\n        "country": "US",\n        "postal_code": "62704"\n      },\n      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s"\n    },\n    "event_details": {\n      "previous": {\n        "address": {\n          "line_1": "123 Main Street",\n          "line_2": "Suite 100",\n          "locality": "Brooklyn",\n          "major_admin_division": "NY",\n          "country": "US",\n          "postal_code": "11201"\n        }\n      }\n    },\n    "custom": {}\n  }\n}'

Request schema

Top-level fields