# Authentication

The Partner API uses API key authentication. All requests must include a valid API key in the `X-Partner-API-Key` header.

## API Key Header

Include your API key with every request:

```
X-Partner-API-Key: your-api-key
```

Example with curl:

```bash
curl -X GET "https://api.app.bullseye.so/api/v1/partner/me" \
  -H "X-Partner-API-Key: your-api-key"
```

## Obtaining API Keys

API keys are created through the Partner API or the partner admin dashboard. Use the [API Keys](/partner-api/api-keys.md) endpoints to:

* List existing API keys
* Create new API keys (with optional scopes and expiration)
* Revoke API keys

When you create an API key, the full key value (`plainKey`) is returned only once. Store it securely; it cannot be retrieved later.

## Key Scopes

API keys can be created with the following scopes:

| Scope   | Description                                          |
| ------- | ---------------------------------------------------- |
| `read`  | Read-only access to partner and organization data    |
| `write` | Read and write access (create, update resources)     |
| `admin` | Full access including API key management and billing |

Keys without explicit scopes default to full access. Use scoped keys for least-privilege access in production.

## Security Best Practices

1. **Never expose keys in client-side code.** API keys must only be used in server-side environments.
2. **Rotate keys periodically.** Create new keys and revoke old ones on a schedule.
3. **Use scoped keys.** Prefer `read` or `write` scopes when full `admin` access is not required.
4. **Set expiration dates.** Use the `expiresAt` parameter when creating keys for temporary access.
5. **Monitor usage.** Review API key usage and revoke compromised keys immediately.

## Unauthorized Responses

If the API key is missing, invalid, or revoked, the API returns:

**Request:**

```
GET /partner/me
```

(No X-Partner-API-Key header or invalid key)

**Response:** `401 Unauthorized`

```json
{
  "code": "Unauthorized",
  "message": "Invalid or missing API key",
  "details": {}
}
```


---

# 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/partner-api/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.