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

# Authentication

> How to authenticate with the Bugzy REST API

## API Keys

All API requests require a Bearer token in the `Authorization` header.

```bash theme={null}
curl -H "Authorization: Bearer bzy_proj_abc123..." \
  https://bugzy.ai/api/v1/projects/{project-id}/executions
```

### Key Types

| Type                      | Prefix      | Scope                           | Status      |
| ------------------------- | ----------- | ------------------------------- | ----------- |
| **Project key**           | `bzy_proj_` | Single project                  | Available   |
| **Team key**              | `bzy_team_` | Selected team endpoints         | Available   |
| **Personal access token** | `bzy_pat_`  | All projects you have access to | Coming soon |

### Generating a Project Key

1. Go to **Dashboard** → **Project Settings** → **API Key**
2. Click **Generate API Key**
3. Copy the key immediately — it's only shown once
4. The key prefix (e.g., `bzy_proj_abc1...`) is stored for identification

Generating a new key revokes the previous one. In-flight requests with the old key will receive `401`.

### Generating a Team Key

Go to **Team Settings** → **API Keys**. Team keys are required for `/api/v1/teams/{team-id}/...` endpoints. Team keys are currently limited to selected team-scoped configuration surfaces such as integrations, environments/env vars, and automations. Execution, test-run, bug-report, and onboarding APIs remain project-scoped. Project keys cannot call team endpoints, and team keys cannot call project endpoints.

## Rate Limiting

All endpoints are rate-limited per API key. Current limits:

* **60 requests per minute** per key

Rate limit headers are included in every response:

| Header                  | Description                           |
| ----------------------- | ------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window           |
| `X-RateLimit-Remaining` | Requests remaining in current window  |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets |

When the limit is exceeded, the API returns `429 Too Many Requests`.

## Error Responses

All errors follow a consistent format:

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

### Error Codes

| Status | Code               | Description                            |
| ------ | ------------------ | -------------------------------------- |
| 400    | `VALIDATION_ERROR` | Invalid request body or parameters     |
| 401    | `UNAUTHORIZED`     | Missing or invalid API key             |
| 404    | `NOT_FOUND`        | Resource not found (or not accessible) |
| 429    | `RATE_LIMITED`     | Rate limit exceeded                    |
| 500    | `INTERNAL_ERROR`   | Internal server error                  |

Note: A `404` is returned for both non-existent resources and resources the API key doesn't have access to (to avoid leaking existence).