Authentication Flow

flowchart TB
    A["API Request with<br/>Authorization: Bearer token"] --> B{"Token present?"}
    B -->|"No"| C["401 MISSING_BEARER_TOKEN"]
    B -->|"Yes"| D{"Valid format?<br/>(≥24 chars)"}
    D -->|"No"| E["401 INVALID_TOKEN_FORMAT"]
    D -->|"Yes"| F{"In auth cache?<br/>(60s TTL)"}
    F -->|"Yes"| G{"Partner status?"}
    F -->|"No"| H["RPC: validate_api_key_and_partner<br/>SHA-256 hash comparison"]
    H -->|"Not found"| I["401 INVALID_TOKEN"]
    H -->|"Found"| G
    G -->|"active"| J["Request authorised"]
    G -->|"suspended"| K["403 PARTNER_SUSPENDED"]
    G -->|"pending"| L["403 PARTNER_NOT_APPROVED"]
    G -->|"inactive"| M["403 PARTNER_INACTIVE"]

    style A fill:#e3f2fd
    style J fill:#e8f5e9
    style C fill:#fce4ec
    style E fill:#fce4ec
    style I fill:#fce4ec
    style K fill:#fff3e0
    style L fill:#fff3e0
    style M fill:#fff3e0

What This Endpoint Does

1. Validates API Key: Checks if the key is valid and not expired
2. Returns Partner Info: Provides partner status, ID, and configuration
3. No Authentication Required: This is the validation endpoint itself

When to Use This Endpoint

• Microservice Authentication: Validate API keys before forwarding requests
• Middleware Integration: Build authentication middleware that verifies keys
• API Gateway Integration: Validate keys at the gateway level
• Partner Verification: Check partner status before processing

Authentication Methods

This endpoint accepts the API key in two ways:

Authorization Header (Recommended)

Authorization: Bearer sk_test_abc123...

Request Body

{"api_key": "sk_test_abc123..."}

Understanding the Response

Success Response (valid: true)

Failed Response (valid: false)

Error Handling

Partner Status Values

Security Considerations

• This endpoint does not require authentication (it IS the validation endpoint)
• Rate limiting applies to prevent brute force attacks
• Invalid API keys don't reveal whether they exist or are simply wrong
• Always use HTTPS to protect API keys in transit

Best Practices

1. Cache validation results: Cache successful validations for 5-15 minutes to reduce latency
2. Handle all status codes: Implement proper error handling for 400, 401, 403, and 500
3. Use Authorization header: Preferred over request body for security and REST conventions
4. Log request_id: Save request_id for debugging and support inquiries
5. Monitor failed validations: Track failed attempts to detect security issues