API Keys

API keys provide a simple authentication mechanism for server-to-server integrations and automation workflows (n8n, Make, custom scripts). Each key is scoped to a tenant and has configurable rate limits.

Authentication Flow

1. Generate an API key via the dashboard or the POST /api-keys endpoint.
2. The full key (e.g. voc_a1b2c3d4...) is returned only once at creation time. Store it securely.
3. Include the key in the X-API-Key header on every request:

curl -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  https://api.usevocals.com/api/v1/agents

4. The API validates the key by hashing it with SHA-256 and matching against the stored hash. The key itself is never stored in plaintext.
5. Rate limits are checked per key using Redis counters (requests per minute and per day).

API keys are prefixed with voc_ and are 8 characters + a URL-safe random token.

Create API Key

POST /api-keys

Generates a new API key. The full key is included in the response only this once -- subsequent list/get calls show only the prefix.

Request Body

{
  "label": "n8n Production",
  "rate_limit_rpm": 60,
  "rate_limit_rpd": 10000
}

Request Fields

Field	Type	Required	Default	Description
label	string	Yes	--	Human-readable label for the key
rate_limit_rpm	integer	No	60	Maximum requests per minute
rate_limit_rpd	integer	No	10000	Maximum requests per day

Response

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "prefix": "voc_a1b2",
  "label": "n8n Production",
  "rate_limit_rpm": 60,
  "rate_limit_rpd": 10000,
  "is_active": true,
  "created_at": "2026-03-01T10:00:00Z",
  "last_used_at": null,
  "key": "voc_a1b2c3d4e5f6g7h8i9j0..."
}

The key field contains the full API key. Save it immediately -- it will not be shown again.

List API Keys

GET /api-keys

Returns all API keys for the current tenant, ordered by creation date (newest first). The full key is never included; only the prefix is shown.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "prefix": "voc_a1b2",
    "label": "n8n Production",
    "rate_limit_rpm": 60,
    "rate_limit_rpd": 10000,
    "is_active": true,
    "created_at": "2026-03-01T10:00:00Z",
    "last_used_at": "2026-03-02T08:15:00Z"
  }
]

Response Fields

Field	Type	Description
id	uuid	API key ID
prefix	string	First 8 characters of the key (for identification)
label	string	Human-readable label
rate_limit_rpm	integer	Requests per minute limit
rate_limit_rpd	integer	Requests per day limit
is_active	boolean	Whether the key is active
created_at	datetime	Creation timestamp
last_used_at	datetime | null	Last time the key was used

Revoke API Key

DELETE /api-keys/{key_id}

Deactivates an API key. The key is not deleted from the database but is marked as inactive and will no longer authenticate requests.

Response

204 No Content

Revocation is immediate. Any in-flight requests using the key may still complete, but subsequent requests will be rejected with 401 Unauthorized.

Rate Limits

Rate limits can be viewed and adjusted through the Rate Limits API:

View Rate Limits

GET /rate-limits

Returns the current rate limit configuration for all active API keys.

[
  {
    "api_key_id": "550e8400-...",
    "label": "n8n Production",
    "prefix": "voc_a1b2",
    "rate_limit_rpm": 60,
    "rate_limit_rpd": 10000
  }
]

Update Rate Limits

PUT /rate-limits/{api_key_id}

Adjust the rate limit thresholds for a specific API key.

Request Body

{
  "rate_limit_rpm": 120,
  "rate_limit_rpd": 50000
}

Response

Returns the updated rate limit configuration.