{
  "info": {
    "name": "Stradum API",
    "description": "Complete API collection for Stradum — behavioral biometrics fraud detection platform.\n\nAuthentication:\n- Publishable key (X-Stradum-Key header with pk_live_*) for SDK endpoints\n- Secret key (X-Stradum-Key header with sk_live_*) for server-side endpoints\n- JWT Bearer tokens for dashboard endpoints (obtained via POST /auth/login)",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://bs-api.up.railway.app",
      "type": "string"
    },
    {
      "key": "publishable_key",
      "value": "pk_live_YOUR_KEY",
      "type": "string"
    },
    {
      "key": "secret_key",
      "value": "sk_live_YOUR_KEY",
      "type": "string"
    },
    {
      "key": "jwt_token",
      "value": "",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "Auth",
      "description": "Registration, login, API key management, and user/team management.",
      "item": [
        {
          "name": "Register",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"admin@example.com\",\n  \"password\": \"securepassword123\",\n  \"org_name\": \"Acme Corp\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/auth/register",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "register"]
            },
            "description": "Create a new organization, owner user, and initial API key pair. Returns publishable_key and secret_key — save these immediately."
          },
          "response": []
        },
        {
          "name": "Login",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if(pm.response.code===200){pm.collectionVariables.set(\"jwt_token\",pm.response.json().token)}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"admin@example.com\",\n  \"password\": \"securepassword123\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/auth/login",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "login"]
            },
            "description": "Authenticate with email/password and receive a JWT. The test script automatically stores the token in the jwt_token collection variable."
          },
          "response": []
        },
        {
          "name": "Current User",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/auth/me",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "me"]
            },
            "description": "Get the currently authenticated user's profile."
          },
          "response": []
        },
        {
          "name": "Create Keys",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"label\": \"Production\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/auth/keys",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "keys"]
            },
            "description": "Generate a new publishable + secret key pair for the organization. Requires owner or admin role."
          },
          "response": []
        },
        {
          "name": "List Keys",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/auth/keys",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "keys"]
            },
            "description": "List all API keys for the organization (prefixes only, full keys are not stored)."
          },
          "response": []
        },
        {
          "name": "Revoke Key",
          "request": {
            "method": "DELETE",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/auth/keys/:key_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "keys", ":key_id"],
              "variable": [
                {
                  "key": "key_id",
                  "value": "",
                  "description": "The ID of the API key to revoke"
                }
              ]
            },
            "description": "Deactivate an API key. Requires owner or admin role."
          },
          "response": []
        },
        {
          "name": "List Users",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/auth/users",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "users"]
            },
            "description": "List all users in the organization."
          },
          "response": []
        },
        {
          "name": "Invite User",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"teammate@example.com\",\n  \"password\": \"temppassword123\",\n  \"role\": \"viewer\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/auth/users/invite",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "users", "invite"]
            },
            "description": "Add a new user to the organization. Valid roles: owner, admin, viewer. Requires owner or admin role."
          },
          "response": []
        },
        {
          "name": "Update User Role",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"role\": \"admin\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/auth/users/:user_id/role",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "users", ":user_id", "role"],
              "variable": [
                {
                  "key": "user_id",
                  "value": "",
                  "description": "The ID of the user to update"
                }
              ]
            },
            "description": "Update a user's role. Valid roles: owner, admin, viewer. Requires owner or admin role."
          },
          "response": []
        },
        {
          "name": "Remove User",
          "request": {
            "method": "DELETE",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/auth/users/:user_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "users", ":user_id"],
              "variable": [
                {
                  "key": "user_id",
                  "value": "",
                  "description": "The ID of the user to remove"
                }
              ]
            },
            "description": "Remove a user from the organization. Cannot remove yourself. Requires owner or admin role."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Sessions",
      "description": "SDK-facing session lifecycle: create, ingest events, complete, and query sessions.",
      "item": [
        {
          "name": "Create Session",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-Stradum-Key",
                "value": "{{publishable_key}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"metadata\": {}\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/sessions",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "sessions"]
            },
            "description": "Initialize a new behavioral capture session. Returns a session_id used for subsequent event ingestion."
          },
          "response": []
        },
        {
          "name": "Ingest Events",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-Stradum-Key",
                "value": "{{publishable_key}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"session_id\": \"SESSION_ID\",\n  \"events\": [\n    {\n      \"event_type\": \"keystroke_down\",\n      \"timestamp\": 1709000000000,\n      \"field_name\": \"email\",\n      \"data\": {\n        \"code\": \"KeyA\",\n        \"key_category\": \"printable\"\n      }\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/sessions/:session_id/events",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "sessions", ":session_id", "events"],
              "variable": [
                {
                  "key": "session_id",
                  "value": "",
                  "description": "The session ID to ingest events for"
                }
              ]
            },
            "description": "Ingest a batch of behavioral events from the SDK. Supports keystroke, mouse, focus, clipboard, scroll, and form snapshot events."
          },
          "response": []
        },
        {
          "name": "Complete Session",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-Stradum-Key",
                "value": "{{publishable_key}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/sessions/:session_id/complete",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "sessions", ":session_id", "complete"],
              "variable": [
                {
                  "key": "session_id",
                  "value": "",
                  "description": "The session ID to complete"
                }
              ]
            },
            "description": "Mark a session as completed, optionally linking identity and field values."
          },
          "response": []
        },
        {
          "name": "Update Metadata",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "X-Stradum-Key",
                "value": "{{publishable_key}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"metadata\": {\n    \"external_id\": \"user-123\"\n  }\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/sessions/:session_id/metadata",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "sessions", ":session_id", "metadata"],
              "variable": [
                {
                  "key": "session_id",
                  "value": "",
                  "description": "The session ID to update metadata for"
                }
              ]
            },
            "description": "Merge metadata into an active session. Uses merge semantics — new keys are added, existing keys are overwritten."
          },
          "response": []
        },
        {
          "name": "List Sessions",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/sessions",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "sessions"],
              "query": [
                {
                  "key": "identity_id",
                  "value": "",
                  "disabled": true,
                  "description": "Filter by identity ID"
                },
                {
                  "key": "account_id",
                  "value": "",
                  "disabled": true,
                  "description": "Filter by account ID"
                },
                {
                  "key": "status",
                  "value": "",
                  "disabled": true,
                  "description": "Filter by status (active, completed)"
                },
                {
                  "key": "risk_level",
                  "value": "",
                  "disabled": true,
                  "description": "Filter by risk level (match, review, mismatch)"
                },
                {
                  "key": "page",
                  "value": "1",
                  "disabled": true
                },
                {
                  "key": "page_size",
                  "value": "50",
                  "disabled": true
                }
              ]
            },
            "description": "List sessions with optional filters for identity, account, status, risk level, category, and metadata."
          },
          "response": []
        },
        {
          "name": "Get Session",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/sessions/:session_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "sessions", ":session_id"],
              "variable": [
                {
                  "key": "session_id",
                  "value": "",
                  "description": "The session ID to retrieve"
                }
              ]
            },
            "description": "Retrieve a single session by ID."
          },
          "response": []
        },
        {
          "name": "Delete Session",
          "request": {
            "method": "DELETE",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/sessions/:session_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "sessions", ":session_id"],
              "variable": [
                {
                  "key": "session_id",
                  "value": "",
                  "description": "The session ID to delete"
                }
              ]
            },
            "description": "Delete a session and all associated data."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Identities",
      "description": "Identity management: create, resolve, link sessions, and query identities and accounts.",
      "item": [
        {
          "name": "Create Identity",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-Stradum-Key",
                "value": "{{secret_key}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"user-123\",\n  \"account_id\": \"acme\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/identities",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "identities"]
            },
            "description": "Create a new identity record linked to an external user ID and optional account."
          },
          "response": []
        },
        {
          "name": "Link Session",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-Stradum-Key",
                "value": "{{secret_key}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"session_id\": \"SESSION_ID\",\n  \"identity_id\": \"IDENTITY_ID\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/identities/:identity_id/sessions/:session_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "identities", ":identity_id", "sessions", ":session_id"],
              "variable": [
                {
                  "key": "identity_id",
                  "value": "",
                  "description": "The identity ID to link"
                },
                {
                  "key": "session_id",
                  "value": "",
                  "description": "The session ID to link"
                }
              ]
            },
            "description": "Link a session to an identity post-submission. Called by the customer's server after form submission to associate the anonymous SDK session with a known identity."
          },
          "response": []
        },
        {
          "name": "Resolve Identity",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-Stradum-Key",
                "value": "{{secret_key}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"user-123\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/identities/resolve",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "identities", "resolve"]
            },
            "description": "Find or create an identity by external ID. Used when the customer knows their internal user ID and wants to ensure a Stradum identity exists for linking."
          },
          "response": []
        },
        {
          "name": "List Identities",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/identities",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "identities"],
              "query": [
                {
                  "key": "account_id",
                  "value": "",
                  "disabled": true,
                  "description": "Filter by account ID"
                },
                {
                  "key": "page",
                  "value": "1",
                  "disabled": true
                },
                {
                  "key": "page_size",
                  "value": "50",
                  "disabled": true
                }
              ]
            },
            "description": "List identities with optional account filter and pagination."
          },
          "response": []
        },
        {
          "name": "Get Identity",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/identities/:identity_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "identities", ":identity_id"],
              "variable": [
                {
                  "key": "identity_id",
                  "value": "",
                  "description": "The identity ID to retrieve"
                }
              ]
            },
            "description": "Retrieve a single identity by ID."
          },
          "response": []
        },
        {
          "name": "List Accounts",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/accounts",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "accounts"]
            },
            "description": "List all customer accounts with session and identity counts."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Analysis",
      "description": "Behavioral analysis: trigger analysis and retrieve results.",
      "item": [
        {
          "name": "Trigger Analysis",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-Stradum-Key",
                "value": "{{secret_key}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"session_id\": \"SESSION_ID\",\n  \"identity_id\": \"IDENTITY_ID\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/analysis/:session_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "analysis", ":session_id"],
              "variable": [
                {
                  "key": "session_id",
                  "value": "",
                  "description": "The session ID to analyze"
                }
              ]
            },
            "description": "Trigger behavioral analysis for a completed session. The session must be completed and linked to an identity. Analysis runs synchronously and returns the full result including risk score, reason codes, and tier breakdown."
          },
          "response": []
        },
        {
          "name": "Get Result",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/analysis/:session_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "analysis", ":session_id"],
              "variable": [
                {
                  "key": "session_id",
                  "value": "",
                  "description": "The session ID to get analysis results for"
                }
              ]
            },
            "description": "Retrieve stored analysis result for a session."
          },
          "response": []
        },
        {
          "name": "Identity Results",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/analysis/identity/:identity_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "analysis", "identity", ":identity_id"],
              "variable": [
                {
                  "key": "identity_id",
                  "value": "",
                  "description": "The identity ID to get all analysis results for"
                }
              ]
            },
            "description": "Retrieve all analysis results for an identity."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Dashboard",
      "description": "Aggregated views optimized for the analyst dashboard.",
      "item": [
        {
          "name": "Auth Check",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/v1/dashboard/auth-check",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "dashboard", "auth-check"]
            },
            "description": "Check whether authentication is required. No auth needed for this endpoint."
          },
          "response": []
        },
        {
          "name": "Overview",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/dashboard/overview",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "dashboard", "overview"]
            },
            "description": "Dashboard landing page metrics: total counts, today's activity, risk distribution, and recent sessions."
          },
          "response": []
        },
        {
          "name": "Identity Profile",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/dashboard/identities/:identity_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "dashboard", "identities", ":identity_id"],
              "variable": [
                {
                  "key": "identity_id",
                  "value": "",
                  "description": "The identity ID to get the behavioral profile for"
                }
              ]
            },
            "description": "Retrieve the full behavioral profile for an identity, including statistical profile with feature means, std deviations, and session history."
          },
          "response": []
        },
        {
          "name": "Alerts",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/dashboard/alerts",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "dashboard", "alerts"],
              "query": [
                {
                  "key": "account_id",
                  "value": "",
                  "disabled": true,
                  "description": "Filter by account ID"
                },
                {
                  "key": "page",
                  "value": "1",
                  "disabled": true
                },
                {
                  "key": "page_size",
                  "value": "50",
                  "disabled": true
                }
              ]
            },
            "description": "List sessions that triggered a REVIEW or MISMATCH alert, enriched with session and account context."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Webhooks",
      "description": "Outbound webhook configuration: register, list, and delete webhook endpoints.",
      "item": [
        {
          "name": "Create Webhook",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-Stradum-Key",
                "value": "{{secret_key}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://example.com/webhook\",\n  \"events\": [\"analysis.completed\"]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/webhooks",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "webhooks"]
            },
            "description": "Register a new webhook endpoint. Specify the URL and the event types to subscribe to."
          },
          "response": []
        },
        {
          "name": "List Webhooks",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/webhooks",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "webhooks"]
            },
            "description": "List all configured webhooks for the organization."
          },
          "response": []
        },
        {
          "name": "Delete Webhook",
          "request": {
            "method": "DELETE",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwt_token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/webhooks/:webhook_id",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "webhooks", ":webhook_id"],
              "variable": [
                {
                  "key": "webhook_id",
                  "value": "",
                  "description": "The webhook ID to delete"
                }
              ]
            },
            "description": "Delete a webhook configuration."
          },
          "response": []
        }
      ]
    }
  ]
}