Core concepts
Authentication
The API authenticates each request with an API key, sent in the
Authorization header. The key identifies an organization: the request only reaches that organization's resources.
| Prefix | Mode | Use |
|---|---|---|
rt_test_ | Test, free | Development |
rt_live_ | Live | Production |
- Send the key only in the
Authorization: Bearer …header, never in the URL. - Call the API from a server: it refuses calls from a browser (CORS). Keep the key in an environment variable or a secrets manager, never in source code.
- The full key is shown only once, at creation. Store it right away.
- A missing, invalid, revoked or expired key gets a
401error (see Errors).
Each key carries the permissions chosen at creation.
| Identifier | In the console | Routes |
|---|---|---|
renders | Renders | POST /v1/renders |
edits | Edits | POST /v1/edits, GET /v1/edit-materials, GET /v1/edit-material-categories |
decorations | Decorations | POST /v1/decorations, GET /v1/styles |
upscales | Upscaling | POST /v1/upscales |
generations_read | Read generations | GET /v1/generations, GET /v1/generations/{id} |
POST /v1/generations/{id}/cancel requires generations_read and the permission of the generation's type. A request without the required permission gets 403 permission_denied.Keys are managed in the console, on the API keys screen.
- A key belongs to the organization, not to its creator.
- The owner, admins and developers create keys. The owner and admins rename, restrict and revoke every key; a developer, their own.
- At most 50 unrevoked keys per organization, expired keys included.
- The console shows the start of each key, its last 4 characters, its last use and the IP address of that use.
- Optional expiry: the key stops working at the end of the chosen day.
- Revocation is immediate and final, from the next request. Revoke an exposed key immediately.
- A revoked or expired key is deleted 13 months after it ends: it is then unknown (
api_key_invalid). Billing members can view keys but not manage them.
A key can be restricted to a list of addresses, at creation or later. A request from another address gets
403 ip_not_allowed.- At most 20 entries: addresses (
203.0.113.4) or CIDR ranges (198.51.100.0/24,2001:db8::/48), IPv4 or IPv6. - Without a list, every address is accepted.
- A change applies from the next request, on
/v1as on the MCP server. - Enter the public outbound address of your servers; the one the console offers is your browser's.
- The list does not apply to the console's playground.
- Create a key with the same permissions.
- Deploy it to your servers.
- When the old key's last use date no longer changes, revoke it.