Authentication Flow

This document explains how authentication works in ThreatWinds.

Authentication Methods

ThreatWinds supports two primary authentication methods:

Authentication Method Description
Bearer Token Authentication Using an Authorization header with a bearer token
API Key Authentication Using API key and API secret headers

Authentication Flow

Bearer Token Authentication

  1. User Login:
    • The client sends the session request to the Auth API
    • The Auth API creates a session, returning a Bearer token and verification ID, and sends a verification code through email
    • The client calls PUT /session/verification with the verificationCodeID and the code to validate the session
  2. Authenticated Request:
    • The client includes the bearer token in the Authorization header of subsequent requests
    • The platform validates the token and checks if the user has the required roles for the requested resource
    • If authorized, the request is processed normally

API Key Authentication

  1. API Key Creation (user-created):
    • The client creates an API key and secret through the Auth API
    • The Auth API returns the key, secret, and verification ID, and sends an email with the verification code
    • The client verifies the creation of the key through the Auth API
  2. API Key Creation (admin-created):
    • An admin creates a user with POST /admin/user. The API key pair is pre-verified — verified is true in the response and no verification code is sent.
    • The key is immediately usable.
  3. Authenticated Request:
    • The client includes the API key and secret in the request headers (api-key and api-secret)
    • The platform validates the key and secret and checks if the API key has the required roles for the requested resource
    • If authorized, the request is processed normally

Partner User Creation

A partner can create end-users on behalf of their customers via POST /partners/user. Partner-created users are automatically marked as verified — they bypass identity verification entirely. No verification code is sent. The response shape and notify flag behave the same as admin user creation; only the "user" role is allowed.

See Partner for details.

Identity Verification

After registration, users can optionally verify their identity. The verification process is progressive:

  1. User initiates verification — POST /api/auth/v2/verify creates a verification session and returns a clientSecret and a hosted url.
  2. Document & selfie capture — The frontend either renders the verification modal using the clientSecret, or redirects the user to the hosted verification url. The user uploads a government-issued ID and completes a live selfie.
  3. Compliance screening — When the identity check is approved, the backend records the result and triggers an automated compliance screen against PEP and sanctions databases.
  4. Verification outcome:
    • Screening clears — The user is marked as verified.
    • Screening flags a hit — The verification attempt is recorded as failed, the attempt counter increments, and the user remains unverified. They may retry if attempts remain.

Users can check progress at any time via GET /api/auth/v2/verify/status.

For full details, see Identity Verification.

Session Management

When using bearer token authentication:

Aspect Description
Session Lifetime Sessions have a limited lifetime
Refresh Responsibility The client is responsible for refreshing the session before it expires
Management Endpoints The Auth API provides endpoints for session management (create, refresh, validate, revoke)

Best Practices

Application Type Recommended Authentication Security Practices
Web Applications Bearer token authentication • Store the token securely (for example, in an HTTP-only cookie)
• Implement token refresh logic
Server-to-Server Communication API key authentication • Store the API key and secret securely
Mobile Applications Bearer token authentication • Store the token securely in the device’s secure storage
• Implement token refresh logic
Documentation Description
Email Authentication Managing email addresses for authentication
Identity Verification Verifying user identity through document and selfie
Session Management Creating and managing user sessions
Key Pair Management Creating and managing API keys
User Management Creating and managing user accounts

Error Response Headers

For responses with status codes other than 200 and 202, the following headers are included:

Header Description
x-error Human-readable error message describing what went wrong
x-error-id Unique identifier for error tracking and support

Error Codes

Status Code Description Possible Cause
400 Bad Request Invalid request parameters or malformed JSON
401 Unauthorized Missing or invalid authentication credentials
403 Forbidden Authenticated user lacks permission for this operation
404 Not Found The requested resource does not exist
500 Internal Server Error Server-side error; please contact support if persistent