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

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
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