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, verification ID and sending a verification code through email
    • The client validates the session through the Auth API
  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:
    • The client creates an API key and secret through the Auth API
    • The Auth API returns the key and secret to the client with a verification ID and sends an email with the verification code
    • The client verifies the creation of the key through the Auth API
  2. 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

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 Stripe Identity verification session and returns a clientSecret.
  2. Document & selfie capture — The frontend renders the Stripe Verify modal using the clientSecret. The user uploads a government-issued ID and completes a live selfie.
  3. Stripe approval — When Stripe approves the submission, a webhook fires (verification.session.verified) and the backend records the result.
  4. NameScan screening — An automated NameScan compliance screen runs against the verified identity data, checking PEP (Politically Exposed Persons) and sanctions databases.
  5. Verification outcome:
    • NameScan clears — The user’s Verified flag is set to true and a user.verified LCE event is published.
    • NameScan 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.

KYC Data Flow

When Stripe approves a verification session (verification.session.verified webhook), personal data is extracted from Stripe’s VerifiedOutputs and LastVerificationReport.Document and stored on the user record. The data flow is:

Stripe webhook → VerifiedOutputs / LastVerificationReport.Document → User record → API responses

The following fields are populated on the user record and returned by GET /verify/status, GET /admin/user/{id}, and GET /admin/users:

  • country — document issuing country (ISO 3166-1 alpha-2)
  • dateOfBirth — date of birth (RFC 3339)
  • addressLine1, addressLine2 — address from the document
  • city, state, postalCode — location from the document
  • nationality — nationality (ISO 3166-1 alpha-3)

These fields are empty until the user completes Stripe Identity verification.

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 Stripe
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 Contains a description of the error that occurred
x-error-id Contains a unique identifier for the error for 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