provod.ai / docs
API

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

FieldTypeDescription
namestring · required1–80 characters after trimming. Required on creation; optional on update.
limitnumber | null0–9999999999.99, up to 8 decimal places. null removes the cap; zero blocks new paid admissions.
limit_resetstring | nulldaily, weekly, monthly, or null (lifetime). Calendar windows use UTC. A non-null reset requires a limit.
disabledbooleanDefault false on creation. true blocks new requests, false re-enables the key.
expires_atstring | nullISO UTC date-time, for example 2030-01-01T00:00:00Z. null removes expiration.
workspace_idstringOptional nonempty assertion of the current workspace; cannot switch workspaces.
include_byok_in_limitfalseOnly 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

FieldTypeDescription
dataobjectKey object.
keystringInference credential secret. Returned only on creation.

Each key includes the current-key fields plus:

FieldTypeDescription
hashstringSHA-256 locator used in the path.
namestringKey name.
disabledbooleanWhether new inference requests are blocked.
created_atstring (date-time)Creation timestamp.
updated_at, last_used_atstring | nullISO 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

HTTPErrorCause
401UnauthorizedMissing, invalid, disabled, revoked or expired key. The X-Org-Id header is also rejected.
403ForbiddenWrong key kind or insufficient workspace access.
400Bad RequestInvalid 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
}

Next steps

On this page