> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.wisprflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

* &#x20;`/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:

```json theme={null}
{
    "detail": "Error message describing the specific issue"
}
```

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

#### Authentication Header Issues

```json theme={null}
{
    "detail": "Authorization header is missing"
}
```

```json theme={null}
{
    "detail": "Authorization header must start with Bearer"
}
```

#### Token Format Issues

```json theme={null}
{
    "detail": "Invalid token format"
}
```

```json theme={null}
{
    "detail": "Invalid token format: missing required fields"
}
```

#### Token Validation Issues

```json theme={null}
{
    "detail": "Invalid token, token not found in database"
}
```

```json theme={null}
{
    "detail": "Token has been revoked"
}
```

```json theme={null}
{
    "detail": "Token has expired"
}
```

```json theme={null}
{
    "detail": "Invalid token, client_id mismatch"
}
```

#### Server Issues

```json theme={null}
{
    "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