Create an API key
Create an inference credential with a spending limit and expiration policy.
Last updated on
POST /v1/keys
Create an inference credential for your application. Save the returned secret immediately: subsequent reads never return it.
Authentication
Authorization: Bearer <MANAGEMENT_API_KEY>: a management key bound to the workspace. The key owner must retain the live permission apiKeys.create.
The credential determines the workspace. X-Org-Id is unsupported.
Request body
Content-Type: application/json
| Field | Type | Description |
|---|---|---|
name | string · required | 1–80 characters after trimming. Required on creation; optional on update. |
limit | number | null | 0–9999999999.99, up to 8 decimal places. null removes the cap; zero blocks new paid admissions. |
limit_reset | string | null | daily, weekly, monthly, or null (lifetime). Calendar windows use UTC. A non-null reset requires a limit. |
disabled | boolean | Default false on creation. true blocks new requests, false re-enables the key. |
expires_at | string | null | ISO UTC date-time, for example 2030-01-01T00:00:00Z. null removes expiration. |
workspace_id | string | Optional nonempty assertion of the current workspace; cannot switch workspaces. |
include_byok_in_limit | false | Only false is accepted. BYOK is unavailable. |
Unknown fields are rejected. On creation, omitted limit means no cap, omitted limit_reset means lifetime, and omitted expires_at means no expiration.
Response · 201
| Field | Type | Description |
|---|---|---|
data | object | Key object. |
key | string | Inference credential secret. Returned only on creation. |
Each key includes the current-key fields plus:
| Field | Type | Description |
|---|---|---|
hash | string | SHA-256 locator used in the path. |
name | string | Key name. |
disabled | boolean | Whether new inference requests are blocked. |
created_at | string (date-time) | Creation timestamp. |
updated_at, last_used_at | string | null | ISO timestamps or null when unavailable. |
With multiple limits, limit, limit_reset and limit_remaining are null; read spend_limits. is_management_key is always false.
Response example
Identifiers and amounts in these examples are illustrative.
Request example
Load the key into a server environment variable. TypeScript uses Node.js fetch; Python uses only the standard library.
const response = await fetch("https://api.provod.ai/v1/keys", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MANAGEMENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "Application worker",
"limit": 1000,
"limit_reset": "monthly"
}),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());Errors
| HTTP | Error | Cause |
|---|---|---|
401 | Unauthorized | Missing, invalid, disabled, revoked or expired key. The X-Org-Id header is also rejected. |
403 | Forbidden | Wrong key kind or insufficient workspace access. |
400 | Bad Request | Invalid or unknown parameters. |
Authentication error example:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key",
"metadata": {}
}
}Operation error example:
{
"message": "limit_reset requires a spending limit",
"error": "Bad Request",
"statusCode": 400
}