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

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

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