Client Side Auth Basics

This section explains how to create and manage client JWT tokens for use in protected endpoints such as /client_api or the /client_ws endpoint. You will use your organization’s API key to generate and revoke these tokens. The tokens themselves expire automatically and can also be revoked at any time.

Workflow Overview

Obtain an Organization API Key

You must have an org-level API key (e.g., Bearer fl-xxxxxx). This key allows you to:

• Generate new client tokens

• Revoke existing tokens

• Revoke all tokens associated with a particular client user ID

Generate a Client Token

Use your org-level API key to call /generate_access_token and receive a JWT token for a specific client. You can store this JWT on the client side. This endpoint takes in a client ID, a duration in seconds for which the token remains valid, and any metadata you choose to send us in the form of a dictionary. The client ID should be consistent for every user of your application.

Client Uses Token

The client calls the “client-facing” endpoints:

• /client_api using the JWT token in the Authorization header like so: Bearer <JWT>

• Client websocket by passing it in the query parameter as ?client_key=Bearer%20<JWT>

Error Responses

All error responses follow a consistent JSON format:

{
    "detail": "Error message describing the specific issue"
}

Here are the exact responses you’ll receive for each error scenario:

Authentication Header Issues

{
    "detail": "Authorization header is missing"
}

{
    "detail": "Authorization header must start with Bearer"
}

Token Format Issues

{
    "detail": "Invalid token format"
}

{
    "detail": "Invalid token format: missing required fields"
}

Token Validation Issues

{
    "detail": "Invalid token, token not found in database"
}

{
    "detail": "Token has been revoked"
}

{
    "detail": "Token has expired"
}

{
    "detail": "Invalid token, client_id mismatch"
}

Server Issues

{
    "detail": "Internal server error during token validation"
}

All error responses will include appropriate HTTP status codes:

• 401 for authentication and token validation issues
• 400 for malformed requests
• 500 for server-side errors

Error Scenarios

When using client authentication, you may encounter various error scenarios. Here’s a comprehensive list of possible errors and their meanings:

Authentication Header Issues (401 Unauthorized)

• Missing Authorization Header: The request is missing the required Authorization header
• Invalid Bearer Format: The Authorization header must start with “Bearer ” followed by the token

Token Format Issues (401 Unauthorized)

• Invalid Token Format: The JWT token is malformed or cannot be decoded
• Missing Required Fields: The token is missing required fields (client_id or token_id)

Token Validation Issues (401 Unauthorized)

• Token Not Found: The token doesn’t exist in our database
• Token Revoked: The token has been explicitly revoked and is no longer valid
• Token Expired: The token has exceeded its expiration time
• Client ID Mismatch: The token’s client ID doesn’t match the expected client

Token Expiration

There are two ways a token can be determined as expired:

1. JWT signature expiration check
2. Database expiration timestamp check

In both cases, you’ll receive a 401 Unauthorized response with the message “Token has expired”

Server Issues (500 Internal Server Error)

In rare cases, you might encounter a server-side error during token validation. This is typically temporary and should be retried.

Handling Token Errors

When encountering these errors, you should:

1. For expired tokens: Generate a new token using your organization API key
2. For revoked tokens: Investigate why the token was revoked and generate a new one if appropriate
3. For format/header issues: Ensure you’re properly formatting the Authorization header as Bearer <token>
4. For client ID mismatches: Ensure you’re using the correct token for the intended client

Best Practices

1. Token Storage: Securely store tokens on the client side
2. Error Handling: Implement proper error handling for all scenarios
3. Token Refresh: Set up automatic token refresh before expiration
4. Logging: Log token validation failures for debugging purposes