API Reference
Manage the credentials used by rendering routes
Use this reference to manage the full API key lifecycle: list, create, update allowlists, rotate, and revoke the machine credentials used by rendering routes.
Machine-readable coverage for API key management lives in /docs/account. The runtime rendering contract that consumes those keys lives in /docs. This page keeps both pieces in one narrative flow so key setup and render usage stay easy to connect.
Auth model
Management routes
Authorization: Bearer ACCESS_TOKEN
Every API key management route uses bearer auth because keys belong to a signed in account.
Runtime usage
X-API-Key header on rendering routes
The created secret is used later on render create, accepted job, and batch routes. This page does not document those render contracts themselves.
Secret visibility
create and rotate only
The full key value is returned only when a key is created or rotated. List and update routes only expose metadata.
Credential owner
Keys belong to the signed in account, so management always starts with bearer auth.
Key modes
The API supports live and test keys for rendering workflows.
Allowlist cap
Each key can carry up to 20 unique IP addresses in its allowlist.
List Keys
List metadata for the account's existing keys
Use the list route when you need key inventory, last-used metadata, allowlist state, or revoked-key history. The response never includes the full secret.
GET/user/api-keys
Request
Use query parameters to narrow inventory, status history, and usage review.
Auth
bearer required
The route lists only keys owned by the authenticated account.
limit
optional integer, 1-1000
Controls the number of key records returned in the current response window.
offset
optional integer, 0+
Moves the response window forward for paginated inventory or revoked-history review.
search
optional string, max 100
Filters by key name or prefix.
status
optional enum: active or revoked
Limits the response to active keys or revoked-history records. Revoked history is capped to the most recent 1000 records.
mode
optional enum: live or test
Filters the response to one key mode.
usage
optional enum: all, used, unused
Distinguishes keys that have already authenticated render traffic from keys that have not.
allowlist
optional enum: all, restricted, open
Filters by whether the key has explicit IP restrictions.
sort
optional enum
Supports created date, last-used date, and name ordering in ascending or descending directions.
Response
List returns metadata only. The full secret value is never included here.
total
number
Total number of keys that match the current filter set.
limit
number
The applied page size for this response window.
offset
number
The applied offset for this response window.
keys
array<object>
Collection of key metadata records for the current page.
keys[].id
string
Identifier for the key record.
keys[].name
string
Human-readable label assigned when the key was created.
keys[].prefix
string
Public prefix used for display and lookup without exposing the full secret.
keys[].mode
live or test
Derived mode for the key based on its prefix.
keys[].status
active or revoked
Current lifecycle state for the key.
keys[].createdAt
ISO 8601 datetime
When the key record was created.
keys[].lastUsedAt
ISO 8601 datetime or null
Timestamp of the most recent successful render request using the key.
keys[].lastUsedIp
string or null
Last observed client IP for successful key usage.
keys[].lastUsedGeo
string or null
Location label derived from the last-used IP when geo lookup is available.
keys[].revokedAt
ISO 8601 datetime or null
Timestamp for revocation when the key is no longer active.
keys[].allowedIps
array<string>
Normalized allowlist values currently attached to the key.
Create Key
Create a new rendering credential and capture the secret immediately
Create is the moment when the full secret is returned. The client should store it securely right away because later routes only return the prefix and metadata.
POST/user/api-keys
Request
Create sends bearer based JSON with the display name, optional mode, and optional IP allowlist for the new key.
Authorization
required header
Use a bearer access token for the signed in account that will own the key.
Content-Type
required header: application/json
Create expects a JSON request body.
name
required string, 1-100
Human-readable label for the key. HTML and control characters are rejected.
mode
optional enum: live or test
Defaults to live when omitted.
allowedIps
optional array, max 20 unique IPs
Restricts the key to specific client IPs. An empty or omitted allowlist means the key is unrestricted.
Response
Create is one of the only times the full secret is returned, so the client must capture it immediately.
id
string
Identifier for the newly created key record.
apiKey
string
The full secret value. This is the only chance to capture it.
prefix
string
Public prefix for display, filtering, and later identification without exposing the full secret.
mode
live or test
The key mode assigned during creation.
Update Key
Update the allowlist without changing the secret
The update route is intentionally narrow. It replaces the key's allowlist and returns a simple success response instead of a new secret.
PATCH/user/api-keys/:id
Request
Update is a narrow bearer based JSON route: identify the key and replace its allowlist.
Authorization
required header
Use a bearer access token for the account that owns the key.
id
required path UUID
Identifies the owned key to update.
Content-Type
required header: application/json
Update expects a JSON request body.
allowedIps
optional array, max 20 unique IPs
This replaces the existing allowlist. Use an empty set to remove restrictions.
Response
Update confirms success, but it never returns a new secret value.
success
success: true
The secret does not change and is never returned here.
Rotate Key
Replace an active key with a new secret in one step
Rotation creates a replacement key, keeps the existing name and allowlist, and immediately revokes the previous active key. Only active owned keys can be rotated.
POST/user/api-keys/:id/rotate
Request
Rotation uses bearer auth plus the key identifier to replace one active key in a single workflow.
Authorization
required header
Use a bearer access token for the account that owns the key.
id
required path UUID
Identifies the active key to replace.
Response
Rotation returns a replacement secret once and revokes the previous active key as part of the same flow. The replacement keeps the prior name, mode, and allowlist.
id
string
Identifier for the replacement key record.
apiKey
string
The new full secret value. This is the only time it is returned.
prefix
string
Public prefix for the replacement key.
mode
live or test
The inherited mode for the replacement key.
Revoke Key
Revoke a key when it should no longer authenticate render requests
Revoke is the terminal lifecycle step for a key. The route marks the owned key as revoked and returns a simple success response.
DELETE/user/api-keys/:id
Request
Revoke uses bearer auth plus the key identifier to terminate that credential.
Authorization
required header
Use a bearer access token for the account that owns the key.
id
required path UUID
Identifies the owned key to revoke.
Response
Revocation returns a simple success shape and uses standard error semantics when the key is missing or not owned by the current account.
success
success: true
The route returns success after the key is revoked. The secret is never returned.
Not found
404 for unknown keys
Revocation only works for keys owned by the current signed in account.
Key Behavior
Understand the lifecycle rules before you automate key management
These are the stable behavior rules that matter most once you move from manual key management into automation.
Behavior to account for in client code and runbooks
One-time secret visibility
create and rotate only
If the client loses the secret from the create or rotate response, it must rotate or create a new key. List routes cannot recover it later.
Plan limits
active key cap by plan
Active key count is plan-limited: free 1, starter 5, professional 10, business 25. Create and rotate can fail with 409 Conflict when that cap would be exceeded.
Allowlist enforcement
exact client IP matching
If allowedIps is configured, render requests using that key only succeed when the normalized client IP is in the allowlist.
Usage metadata
lastUsedAt, lastUsedIp, lastUsedGeo
Successful key usage updates last-used metadata. lastUsedGeo is a location label string when lookup data is available. IP changes can also trigger anomaly audit events and account email notifications.
Rotation semantics
create replacement, revoke previous
Rotation is not an in-place mutation. It creates a new key, preserves the important settings, and revokes the previous active key.
The practical rule is simple: treat the secret as write-only, treat allowlists as exact runtime controls, and treat rotation as a replacement workflow rather than a metadata edit.
Next Steps
Move from credential management into the auth model, render contract, or rotation guide
Use the pages below when you need the mental model behind credential choice, the render contract that consumes the key, or the operational guide for safe rotation and recovery.
Need the auth split?
Open auth models concept page
Use the concept page when you need the API key versus bearer versus public-flow mental model.
Need the main key-consuming route?
Open single render reference
Use the single render page for the request contract that actually uses the X-API-Key header.
Need the operational workflow?
Open key rotation and recovery guide
Use the guide for rollout sequencing, incident response, and safe rotation practices.