# API Keys

Manage Organization API keys for programmatic access. Keys allow server-to-server integrations to authenticate without browser sessions.

API keys are created in the Bullseye dashboard under **Organization Settings > API Keys**. Once created, use the `X-API-Key` header to authenticate all API requests.

## List API Keys

Returns all API keys for the specified organization. Key hashes are never returned — only the prefix is included for identification.

```
GET /organization/{organization_id}/api-keys
```

### Example

```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"
```

### Response

```json
{
  "apiKeys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "org_abc123",
      "createdByUserId": "user_xyz",
      "name": "Production Server",
      "keyPrefix": "bsk_live_a1b2",
      "scopes": ["read", "write"],
      "status": "active",
      "expiresAt": null,
      "lastUsedAt": "2026-02-20T15:30:00Z",
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ]
}
```

### Fields

| Field             | Type           | Description                                           |
| ----------------- | -------------- | ----------------------------------------------------- |
| `id`              | string         | Unique key identifier                                 |
| `organizationId`  | string         | Organization the key belongs to                       |
| `createdByUserId` | string         | User who created the key                              |
| `name`            | string         | Human-readable key name                               |
| `keyPrefix`       | string         | First 12 characters of the key for identification     |
| `scopes`          | string\[]      | Permissions granted to this key                       |
| `status`          | string         | `active` or `revoked`                                 |
| `expiresAt`       | string \| null | ISO 8601 expiration date, or null if no expiry        |
| `lastUsedAt`      | string \| null | ISO 8601 timestamp of last use, or null if never used |
| `createdAt`       | string         | ISO 8601 creation timestamp                           |

## Create API Key

Creates a new API key and returns the full plain-text key. The plain key is returned only once in this response — store it securely.

Requires an existing API key with `admin` scope.

```
POST /organization/{organization_id}/api-keys
```

### Request Body

| Field       | Type      | Required | Description                                           |
| ----------- | --------- | -------- | ----------------------------------------------------- |
| `name`      | string    | Yes      | Human-readable name for the key                       |
| `scopes`    | string\[] | No       | Permissions to grant. Defaults to `["read", "write"]` |
| `expiresAt` | string    | No       | RFC 3339 expiration date                              |

### Example

```bash
curl -X POST "https://api.app.bullseye.so/api/v1/organization/{org_id}/api-keys" \
  -H "X-API-Key: bsk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "scopes": ["read", "write"]
  }'
```

### Response

```json
{
  "apiKey": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org_abc123",
    "createdByUserId": "user_xyz",
    "name": "Production Server",
    "keyPrefix": "bsk_live_a1b2",
    "scopes": ["read", "write"],
    "status": "active",
    "expiresAt": null,
    "lastUsedAt": null,
    "createdAt": "2026-02-27T10:00:00Z"
  },
  "plainKey": "bsk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
```

The `plainKey` field contains the full API key. Copy and store it securely — it cannot be retrieved again.

## Revoke API Key

Permanently revokes an API key. Any requests using the revoked key will receive a 401 response. This action cannot be undone.

Requires an API key with `admin` scope.

```
DELETE /organization/{organization_id}/api-keys/{key_id}
```

### Example

```bash
curl -X DELETE "https://api.app.bullseye.so/api/v1/organization/{org_id}/api-keys/{key_id}" \
  -H "X-API-Key: bsk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
```

### Response

```json
{
  "success": true
}
```

## Required Scopes

| Endpoint   | Required Scope |
| ---------- | -------------- |
| List keys  | `read`         |
| Create key | `admin`        |
| Revoke key | `admin`        |

Your first API key is created in the Bullseye dashboard. After that, keys with `admin` scope can create and revoke additional keys programmatically.

## Errors

| Status | Description                                             |
| ------ | ------------------------------------------------------- |
| 400    | Bad Request – Missing required fields or invalid format |
| 401    | Unauthorized – Invalid, missing, or revoked API key     |
| 500    | Internal Server Error                                   |


---

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