API Keys

Manage API keys for your organization. Keys are used for Bearer token authentication.

Create API Key

POST /v1/api_keys

Request Body:

Field	Type	Required	Description
`name`	string	yes	Display name for the key
`scopes`	string[]	no	Permissions (default: all scopes)

Response: 200 OK — Returns the key object including the secret (shown only once).

List API Keys

GET /v1/api_keys

Returns all API keys for the organization. Secrets are masked.

Rotate API Key

POST /v1/api_keys/{key_id}/rotate

Generates a new secret for the key. The old secret remains valid for 24 hours (overlap window).

Revoke API Key

POST /v1/api_keys/{key_id}/revoke

Immediately revokes the key. This action cannot be undone.

Response: 204 No Content

Available Scopes

When creating an API key, you can restrict its permissions using scopes. If no scopes are specified, the key receives all scopes by default.

Scope	Description
`jobs:write`	Create and cancel jobs
`jobs:read`	List and get job details, files, submissions
`webhooks:write`	Create, update, delete webhook endpoints
`webhooks:read`	List webhook endpoints and events
`keys:manage`	Create, rotate, revoke API keys
`audit:read`	Read audit log events
`usage:read`	Read billing and usage data
`billing:write`	Purchase credits, manage billing

Example: Create a read-only key

curl -X POST https://api.firsthandapi.com/v1/api_keys \
  -H "Authorization: Bearer fh_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-only dashboard key",
    "scopes": ["jobs:read", "usage:read"]
  }'

Submissions Webhooks