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

# Authentication

> Authenticate with the Felan REST API using a team-scoped API key.

## Team API keys

Public API routes accept a team API key as a Bearer token:

```bash theme={null}
curl "https://app.felan.ai/api/v1/teams/{team-slug}" \
  -H "Authorization: Bearer bzy_team_abc123..."
```

Create and revoke keys from **Settings → API Keys** for the selected Felan team. A new key is displayed once; copy it to your secret manager before closing the dialog.

Each key can access only its team's API resources. Use the team slug shown in the dashboard URL or under **Team Settings → General Settings**. A request for another team slug returns `404 Not Found` so the other team's existence is not disclosed.

<Info>
  Felan team keys retain the `bzy_team_` compatibility prefix. Other prefixes are rejected by the current public API.
</Info>

## Rate limiting

Each team API key is limited to 60 requests per minute. Authenticated responses include:

* `X-RateLimit-Limit`
* `X-RateLimit-Remaining`
* `X-RateLimit-Reset` as a Unix timestamp in seconds

Requests beyond the limit return `429 Too Many Requests`.

## Error responses

API errors use a consistent envelope:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
```

| Status | Code                                                                          | Meaning                                                                     |
| ------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 400    | `VALIDATION_ERROR`                                                            | A request field or parameter is invalid                                     |
| 401    | `UNAUTHORIZED`                                                                | The Bearer token is missing, invalid, revoked, or has an unsupported prefix |
| 402    | `EXECUTION_DENIED`                                                            | The team is not currently admitted to start or resume session execution     |
| 404    | `NOT_FOUND`                                                                   | The resource is missing or belongs to another team                          |
| 409    | `CONFLICT`                                                                    | The requested create conflicts with an existing resource                    |
| 429    | `RATE_LIMITED`                                                                | The key exceeded its request limit                                          |
| 500    | `INTERNAL_ERROR`                                                              | The server could not complete the request                                   |
| 502    | `SESSION_START_FAILED`, `SESSION_PUBLISH_FAILED`, or `MESSAGE_PUBLISH_FAILED` | The runtime or inbound publisher could not accept session work              |