---
title: API keys · API reference
url: https://docs.schemalabs.ai/api-reference/keys
description: List, create, rotate, and revoke org-scoped API keys carrying the read, run, serve, manage, and delete scopes.
---

# API keys

> List, create, rotate, and revoke org-scoped API keys carrying the read, run, serve, manage, and delete scopes.

API keys are org-scoped credentials with an operation scope. Outputs are bundled, so keys are never scoped per output. The secret (`sk_live_...`) is shown once at creation and never again; the key id (`key_...`) is what listings show.

Scopes: `read` (list and get endpoints, data, reports, jobs, usage, models, keys), `run` (stateless inference on the bases), `serve` (call live endpoints), `manage` (create endpoints, refresh, upgrade, data connect, sync, pin, generate, cancel jobs, manage keys), `delete` (remove endpoints and data, revoke keys). Reports are managed on the platform’s Reports page.

## The key object

**Attributes**

- `id` (string): `key_...`, immutable.
- `name` (string): Display name, for example `pipeline-prod`.
- `key_preview` (string): First and last characters of the secret for recognition, for example `sk_liv...a1b2`.
- `scopes` (array of strings): Any of `read`, `run`, `serve`, `manage`, `delete`.
- `rate_limit` (integer): The key’s request ceiling in requests per minute; the value reflects your plan.
- `requests` (integer): Requests made with this key.
- `created_at` (string): Creation time.
- `last_used` (string | null): Last request time.
- `key` (string): The full secret. Present only in the create and rotate responses, shown once.

```json
{
  "id": "key_77ab",
  "name": "pipeline-prod",
  "key_preview": "sk_liv...a1b2",
  "rate_limit": 600,
  "requests": 1042,
  "scopes": [
    "serve"
  ],
  "created_at": "2026-08-01T10:00:00Z",
  "last_used": "2026-08-16T09:12:04Z"
}
```

## Operations

### List keys

`GET /v2/keys` (scope: `read`)

Lists the organization’s API keys, without secrets.

**Returns**

A list of key objects.

**Example request (cURL)**

```bash
curl 'https://api.schemalabs.ai/v2/keys' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"
```

**Example response (200)**

```json
{
  "keys": [
    {
      "id": "key_77ab",
      "name": "pipeline-prod",
      "key_preview": "sk_liv...a1b2",
      "rate_limit": 600,
      "requests": 1042,
      "scopes": [
        "serve"
      ],
      "created_at": "2026-08-01T10:00:00Z",
      "last_used": "2026-08-16T09:12:04Z"
    },
    {
      "id": "key_10c2",
      "name": "ci",
      "key_preview": "sk_liv...2c8e",
      "rate_limit": 600,
      "requests": 88,
      "scopes": [
        "read",
        "run",
        "manage"
      ],
      "created_at": "2026-07-20T15:32:00Z",
      "last_used": "2026-08-15T22:01:40Z"
    }
  ],
  "request_id": "req_8f2c1a"
}
```

### Create a key

`POST /v2/keys` (scope: `manage`)

Creates an API key. The secret is returned once, in this response only.

**Body** (application/json)

- `name` (string, required): Display name.
- `scopes` (array of strings, required): One or more of `read`, `run`, `serve`, `manage`, `delete`.

**Returns**

The key object including `key`, the full secret, shown once.

**Example request (cURL)**

```bash
curl -X POST 'https://api.schemalabs.ai/v2/keys' \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "pipeline-prod", "scopes": ["serve"] }'
```

**Example response (201)**

```json
{
  "id": "key_77ab",
  "name": "pipeline-prod",
  "key_preview": "sk_liv...a1b2",
  "rate_limit": 600,
  "requests": 0,
  "scopes": [
    "serve"
  ],
  "created_at": "2026-08-01T10:00:00Z",
  "last_used": null,
  "key": "<API key secret, shown once>"
}
```

> Key and billing management also live on the platform’s API page. Store the secret in a secrets manager; it cannot be retrieved again.

### Rotate a key

`POST /v2/keys/:id/rotate` (scope: `manage`)

Issues a new secret for the key and invalidates the old one immediately. Same id, same scopes.

**Path parameters**

- `id` (string, required): `key_...`.

**Returns**

The key object with the new secret in `key`, shown once. The old secret stops working immediately.

**Example request (cURL)**

```bash
curl -X POST 'https://api.schemalabs.ai/v2/keys/key_77ab/rotate' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"
```

**Example response (200)**

```json
{
  "id": "key_77ab",
  "name": "pipeline-prod",
  "key_preview": "sk_liv...9f4d",
  "rate_limit": 600,
  "requests": 0,
  "scopes": [
    "serve"
  ],
  "created_at": "2026-08-01T10:00:00Z",
  "last_used": null,
  "key": "<new API key secret, shown once>"
}
```

### Revoke a key

`DELETE /v2/keys/:id` (scope: `delete`)

Revokes a key immediately. The key stops working and leaves the listing.

**Path parameters**

- `id` (string, required): `key_...`.

**Returns**

A deletion confirmation.

**Example request (cURL)**

```bash
curl -X DELETE 'https://api.schemalabs.ai/v2/keys/key_10c2' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"
```

**Example response (200)**

```json
{
  "deleted": true,
  "id": "key_10c2"
}
```