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

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

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

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

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

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

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

Authentication Visitors