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

# Authentication

> Authenticate Woes REST API requests with workspace API keys.

# Authentication

The Woes REST API uses workspace API keys. Create a key in **Settings → Keys**,
copy the full secret once, and store it in your server-side secret manager.

## Bearer Token

Pass the key in the `Authorization` header.

```bash theme={null}
curl https://woes.dev/api/v1/conversations \
  -H "Authorization: Bearer $WOES_API_KEY"
```

## Quick API Examples

These examples use the Conversations API because it is the first public Woes API
surface. The API key must be a workspace API key that starts with `woesk_`.

### List conversations

```bash theme={null}
curl "https://woes.dev/api/v1/conversations?status=open&limit=10" \
  -H "Authorization: Bearer $WOES_API_KEY"
```

### Create a conversation

```bash theme={null}
curl https://woes.dev/api/v1/conversations \
  -X POST \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ticket_123",
    "subject": "Need help with auth",
    "customer": {
      "id": "cus_123",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "company": "Example API Co"
    }
  }'
```

### Add a message

```bash theme={null}
curl https://woes.dev/api/v1/conversations/{conversationId}/messages \
  -X POST \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "body": "I am getting a 401 from POST /orders."
  }'
```

See [Conversations](/api/conversations) for every supported conversation
endpoint, request field, and response shape.

## Security Rules

* Keep `woesk_` keys on your backend.
* Do not put REST API keys in widget snippets or client-side JavaScript.
* Revoke keys from **Settings → Keys** when rotating credentials.
* Each key is workspace-scoped; it cannot read or write another workspace.

## Error Responses

| Status | Code             | Meaning                                 |
| ------ | ---------------- | --------------------------------------- |
| `401`  | `unauthorized`   | Missing, unknown, or revoked API key.   |
| `401`  | `key_expired`    | API key has expired.                    |
| `429`  | `rate_limited`   | Too many requests for the key.          |
| `500`  | `internal_error` | The API request could not be completed. |

```json theme={null}
{
  "code": "unauthorized",
  "error": "A valid workspace API key is required."
}
```