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

# Authentication

> Obtain a short-lived session token to authenticate your WebSocket connection.

## Token Endpoint

To start a voice session, send a POST request with your API key to receive a session token and WebSocket URL.

```bash theme={null}
POST /api/v1/sdk/token
Authorization: Bearer <your_api_key>
```

## Response

On success, the server returns a JSON object with two fields:

```json theme={null}
{
  "token": "<session_token>",
  "ws_url": "wss://host/api/v1/sdk/ws"
}
```

| Field    | Description                                                                         |
| -------- | ----------------------------------------------------------------------------------- |
| `token`  | Short-lived JWT valid for 5 minutes. Used to authenticate the WebSocket connection. |
| `ws_url` | The WebSocket endpoint URL to connect to.                                           |

## Error Responses

| Status             | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| 401 Unauthorized   | Invalid or missing API key. Check your Authorization header. |
| 403 Forbidden      | API key is valid but the kiosk is inactive or disabled.      |
| 500 Internal Error | Server-side issue. Retry after a short delay.                |

## Best Practices

* Request a **fresh token** for each voice session — do not cache or reuse tokens
* Use the token **immediately** after receiving it — it expires in 5 minutes
* If the WebSocket connection fails, request a new token before reconnecting
* Handle authentication errors gracefully and provide user feedback

## Health Check

Use the heartbeat endpoint to verify your API key and check server availability before starting a session.

```bash theme={null}
POST /api/v1/sdk/heartbeat
Authorization: Bearer <your_api_key>

// Response 200
{ "status": "ok" }
```

## Next Steps

Once you have a token, continue to the [WebSocket Protocol](/websocket) page to learn how to establish the connection and start streaming audio.