> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication reference

> Credential formats, environment variables, token limits, and compatibility behavior.

This page lists the exact formats, limits, and precedence rules for Mesa credentials. For the recommended setup, see [Authentication](/content/concepts/authentication); for a step-by-step migration, see [Migrate from API keys](/content/getting-started/migrate-from-api-keys).

## Credentials

| Credential   | Format                         | Intended location                                       |
| ------------ | ------------------------------ | ------------------------------------------------------- |
| Private key  | `mesa_private_key_<org>_<key>` | Trusted backend, orchestrator, or CI secret             |
| Public key   | `mesa_public_key_<key>`        | Registered with Mesa                                    |
| Access token | Compact JWT                    | API requests, sandboxes, jobs, the CLI, and MCP clients |
| API key      | `mesa_...`                     | Compatible trusted-process credential (deprecated)      |

Keys are Ed25519 pairs. The private key is bound to a single organization and is never sent to Mesa. Revoking the registered public key invalidates every token the private key signed.

## Token behavior

|                                  | Private-key token               | API-key token                                    |
| -------------------------------- | ------------------------------- | ------------------------------------------------ |
| Signing algorithm                | Ed25519                         | HS256                                            |
| Default lifetime                 | 15 minutes                      | 1 hour                                           |
| Maximum lifetime                 | 4 hours                         | 24 hours                                         |
| Authors                          | Required when explicitly minted | Not accepted                                     |
| Scopes                           | `read`, `write`, `admin`        | `read`, `write`, `admin`, limited by the API key |
| Repository restriction           | `repos` or `repo_ids`           | `repos` or `repo_ids`, limited by the API key    |
| Individual refresh or revocation | Not supported                   | Not supported                                    |

To restrict a token to specific repositories, pass either `repos` (full `org/repo` names) or `repo_ids` (canonical repository IDs, at most 250 entries). The two fields are mutually exclusive.

Private-key `tokens.create(...)` calls require at least one author. Each author has a nonblank `name` and an optional `email`. The `authors` list keeps the order you supply and holds at most 100 entries.

The token authors apply to commits Mesa creates through SDK and MesaFS operations.

Minting always happens in a trusted process (ex. your application server), from a private-key or API-key client. An access-token client cannot mint further tokens.

## SDK credentials

TypeScript accepts exactly one of `apiKey`, `privateKey`, or `auth`. Python accepts exactly one of `api_key`, `private_key`, or `auth`.

The `auth` object contains either a private key or an existing access token. An access-token client derives its organization from the token and forwards the token unchanged on every request. Only private-key tokens work here. API-key tokens carry no organization claim, so the constructor rejects them, though they remain valid for the CLI, REST, and MesaFS mounts.

When no explicit credential is provided, the SDKs read from the environment, checking `MESA_API_KEY` before `MESA_PRIVATE_KEY`.

## CLI credentials

| Variable            | Purpose                                 |
| ------------------- | --------------------------------------- |
| `MESA_ACCESS_TOKEN` | Preferred bearer credential for the CLI |
| `MESA_API_KEY`      | Compatible API-key credential           |
| `MESA_ORG`          | Organization mounted by the CLI         |

The CLI forwards `MESA_ACCESS_TOKEN` unchanged. If `MESA_API_KEY` is also set, the API key takes precedence.

## HTTP credentials

REST and MCP requests use `Authorization: Bearer <credential>`.

API keys are deprecated but remain accepted anywhere existing integrations already use them.