# Authentication

Authenticate API requests using an **Organization API Key**. Include your key in the `X-API-Key` header on every request.

## Obtaining an API Key

1. Sign in to the Bullseye dashboard at [app.bullseye.so](https://app.bullseye.so)
2. Go to **Organization Settings > API Keys**
3. Click **Create API Key** and select the scopes your integration needs
4. Copy the key immediately — it is shown only once

Keys follow the format `bsk_live_` followed by 32 hexadecimal characters.

## Header Format

```
X-API-Key: bsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Example Request

```bash
curl -X GET "https://api.app.bullseye.so/api/v1/organization/{org_id}/api-keys" \
  -H "X-API-Key: bsk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -H "Content-Type: application/json"
```

## Scopes

Each API key has one or more scopes that control what it can access:

| Scope          | Access                                                            |
| -------------- | ----------------------------------------------------------------- |
| `read`         | View visitors, companies, lists, and analytics                    |
| `write`        | Create and update lists, ICP configs, and settings                |
| `admin`        | Full access including API key management (grants all base scopes) |
| `agency:read`  | View agency overview and sub-organizations (agency accounts only) |
| `agency:write` | Create and manage sub-organizations (agency accounts only)        |

When creating a key, select only the scopes your integration requires. You can always create additional keys with different scopes for different use cases.

## Rate Limiting

API requests are rate limited to **1,000 requests per minute** per key. Rate limit information is included in response headers:

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

When the rate limit is exceeded, the API returns a `429 Too Many Requests` response with a `Retry-After` header indicating how long to wait. Implement exponential backoff when handling rate limit errors.

## Key Management

After creating your first key in the dashboard, keys with `admin` scope can create and revoke additional keys programmatically. See [API Keys](/api-reference/api-keys.md) for the key management endpoints.

## Security Best Practices

* Grant only the scopes your integration needs
* Set an expiration date for keys used in temporary or staging environments
* Rotate keys periodically — create a new key, update your integration, then revoke the old one
* Never commit keys to version control or expose them in client-side code
* Use separate keys for different environments (production, staging)

## Errors

| Status | Description                                                             |
| ------ | ----------------------------------------------------------------------- |
| 401    | Unauthorized – API key is missing, expired, revoked, or invalid         |
| 403    | Forbidden – API key does not have the required scope for this endpoint  |
| 429    | Too Many Requests – Rate limit exceeded. Check the `Retry-After` header |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bullseye.so/api-reference/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.