---
title: Authentication
url: https://docs.schemalabs.ai/authentication
description: API keys, scopes, and how the platform and the API share one identity and one meter.
---

# Authentication

> API keys, scopes, and how the platform and the API share one identity and one meter.

Every API request carries an org-scoped API key as a bearer token:

```http
Authorization: Bearer <API key>
```

Keys are created on the platform's **API** page or with [`POST /v2/keys`](https://docs.schemalabs.ai/api-reference/keys#create-key). The secret is shown once, at creation, and never again; listings show the key id (`key_...`) and a preview of the secret. Store secrets in a secrets manager and rotate with [`POST /v2/keys/:id/rotate`](https://docs.schemalabs.ai/api-reference/keys#rotate-key).

## Two modes, one org

| Mode | Who | How | Bills to |
|---|---|---|---|
| Interactive | Humans | Web sign-in on [platform.schemalabs.ai](https://platform.schemalabs.ai) | the org |
| Headless | CI, agents, pipelines, apps | `Authorization: Bearer $SCHEMA_API_KEY` | the same org |

An endpoint created over the API appears in the platform Endpoints list immediately. Usage from both surfaces draws one org meter and one bill; the Usage page and [`GET /v2/usage`](https://docs.schemalabs.ai/api-reference/usage) render the same numbers, broken down by surface.

## Scopes

Outputs are bundled, so keys are never scoped per output. They are scoped by operation:

| Scope | Allows |
|---|---|
| `read` | List and get endpoints, data, reports, jobs, usage, models, keys |
| `run` | Stateless inference on the base models: `POST /v2/run` |
| `serve` | Call live endpoints: `POST /v2/serve/:id` |
| `manage` | Create endpoints, refresh, upgrade, connect and sync data, pin and unpin, generate synthetic data, cancel jobs, manage keys |
| `delete` | Delete endpoints and data, revoke keys |

A key can hold any combination. Give production systems the least they need: a pipeline that only serves endpoints needs `serve` alone.

## Errors

| Situation | Response |
|---|---|
| Missing or malformed key | `401` `auth_error` |
| Key revoked | `401` `auth_error` |
| Key lacks the route's scope | `403` `auth_error` |

See [Errors](https://docs.schemalabs.ai/api-reference#errors) for the envelope.

## What a key covers

A key buys inference: `run` returns the output bundle, and an endpoint serves your configuration over the shared base (or an Enterprise fine-tune) at a URL. Connection credentials you register are encrypted at rest and write-only.