Create API Key

What it does

Creates a new API key for an application. The response contains the key value itself — this is the only time it is ever returned. Later reads expose the key’s metadata (name, expiry, status) but never the secret again.

The key value is shown once. Store it in your secret manager the moment you receive it. If it is lost, the only remedy is to create a new key.

Endpoint

POST /api/v1/apps/{app_id}/api-keys

Headers

string

required

Secret key in Bearer sk_... format. See Secret Key authentication.

string

required

Always application/json.

Path parameters

string

required

Application ID the key is issued for. Must belong to the organization (otherwise 404).

Request Body

string

required

A label for the key. Use something that identifies where the key is deployed (prod-backend, ci-pipeline) — it is how you will recognise the key later, since the value itself is not visible.

string

ISO-8601 timestamp at which the key stops working. Must be in the future.

Set an expiry even for long-lived keys, and rotate before it lands: create the new key, deploy it, then let the old one expire. That way a rotation never needs a window where no valid key exists.

Response

boolean

true when the key was created.

object

The created key.

Show data

string

UUID of the key record. Use this to refer to the key afterwards.

string

The application the key belongs to.

string

The label you supplied.

string

The key value — returned only in this response. Not retrievable afterwards.

boolean

Whether the key is currently usable.

string

ISO-8601 expiry timestamp.

string

ISO-8601 creation timestamp.

Examples

Demo 1 — create a key with an expiry

POST /api/v1/apps/app_7poyXj8GXuv76e/api-keys
Authorization: Bearer sk_...
Content-Type: application/json

{
  "name": "prod-backend",
  "expiresAt": "2027-08-20T13:27:30.368Z"
}

{
  "data": {
    "id": "47fee6cf-9634-47b2-882f-4e9b90e57158",
    "appId": "app_7poyXj8GXuv76e",
    "name": "prod-backend",
    "key": "<secret_key>",
    "isActive": true,
    "expiresAt": "2027-08-20T13:27:30.368000Z",
    "createdAt": "2026-08-20T13:33:15.985914Z"
  },
  "isSuccess": true
}

Copy data.key now — the next read of this key will not include it.

Demo 2 — error: missing name → 400

POST /api/v1/apps/app_7poyXj8GXuv76e/api-keys
Authorization: Bearer sk_...
Content-Type: application/json

{ "expiresAt": "2027-08-20T13:27:30.368Z" }

{ "errors": { "code": "REQ_001", "group": "VALIDATION", "description": "Missing required field: name" }, "isSuccess": false }

Demo 3 — error: expiresAt in the past → 422

POST /api/v1/apps/app_7poyXj8GXuv76e/api-keys
Authorization: Bearer sk_...
Content-Type: application/json

{ "name": "stale-key", "expiresAt": "2025-01-01T00:00:00Z" }

{
  "errors": {
    "code": "VAL_000",
    "group": "VALIDATION",
    "description": "Validation failed.",
    "fields": {
      "expiresAt": { "code": "VAL_018", "description": "Date must be in the future." }
    }
  },
  "isSuccess": false
}

Errors

object

Error details with code, group, and description; isSuccess is false.

HTTP	Code	Group	When
400	`REQ_001`	`VALIDATION`	Missing required field or invalid JSON.
401	`ORGANIZATION_SECRET_010`	`NOT_FOUND`	Authorization / secret key is missing.
401	`ORGANIZATION_SECRET_011`	`NOT_FOUND`	Secret key is invalid.
404	`APPLICATION_004`	`NOT_FOUND`	`app_id` does not belong to the organization.
422	`VAL_000`	`VALIDATION`	Field validation — `expiresAt` not in the future, invalid date format, `name` length. Each offending field is listed under `errors.fields`.

Getting Started

Analytics

Application

Template

Media

Developers

Reference

What it does

Endpoint

Headers

Path parameters

Request Body

Response

Examples

Errors

Next steps

Authentication

Update Webhook

​What it does

​Endpoint

​Headers

​Path parameters

​Request Body

​Response

​Examples

​Errors

​Next steps

Authentication

Update Webhook

What it does

Endpoint

Headers

Path parameters

Request Body

Response

Examples

Errors

Next steps