> ## 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, and token limits.

This page lists the exact formats, limits, and precedence rules for Mesa credentials. For the recommended setup, see [Authentication](/content/concepts/authentication).

## 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, and the CLI  |

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

| Property                         | Behavior                                             |
| -------------------------------- | ---------------------------------------------------- |
| Signing algorithm                | Ed25519                                              |
| Default lifetime                 | 15 minutes                                           |
| Maximum lifetime                 | 4 hours                                              |
| Authors                          | Required when explicitly minted                      |
| Permissions                      | `read-repo` or `write-repo`, derived from the layout |
| Repository restriction           | Repository names from the layout                     |
| Individual refresh or revocation | Not supported                                        |

The TypeScript and Python SDKs mint private-key tokens through filesystem definitions. `mesa.fs(...)` collects every repository in the layout and grants the permissions you specify. `definition.token()` returns that short-lived access token, while `definition.layout()` returns the matching validated, raw `Layout`. Serialize it with `JSON.stringify(...)` in TypeScript or `json.dumps(...)` in Python to produce the document for `mesa mount --layout`.

Private-key layout definitions 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.

In the TypeScript and Python SDKs, minting happens in a trusted process from a private-key client, through a layout definition: `mesa.fs({ layout, ttl }).token()`.

Every minted token names the repositories it can reach. The SDKs cannot export an organization-wide access token; code needing organization-wide authority holds the private key and uses `new Mesa({ privateKey })`, which signs a fresh organization-scoped token per request without handing one out.

## SDK private keys

TypeScript and Python accept only an optional private key and do not accept access tokens.

Pass the TypeScript key as `new Mesa({ privateKey })` and the Python key as `Mesa(private_key=private_key)`, or omit it to read `MESA_PRIVATE_KEY`. Access tokens are intended for the CLI, MesaFS, or direct REST requests, not for constructing another SDK client. The CLI requires an Ed25519 `MESA_ACCESS_TOKEN` and derives its organization from that token's issuer.

## Ed25519 token compatibility

The backend accepts both current repository-grant tokens and Ed25519 tokens minted by older private-key SDKs. Current tokens contain `access` or internal `admin` authority and use the plural `authors` object array. Older tokens contain `scopes`, may restrict `repos` or `repo_ids`, and use the historical singular `author` claim.

Current SDKs only mint the new format. Legacy Ed25519 verification remains available so existing deployed clients continue to work.

## CLI access token

| Variable            | Purpose                         |
| ------------------- | ------------------------------- |
| `MESA_ACCESS_TOKEN` | Global access token for the CLI |

Set `MESA_ACCESS_TOKEN` for CLI access. It is the CLI's only access token and organization source, and it must be an Ed25519 Mesa access token with an organization issuer. Both legacy and current Ed25519 private-key JWTs carry the issuer needed for this path. The CLI does not read credentials or organizations from `credentials.toml`, `MESA_ORG`, `MESA_ORGS`, or repository `--org` flags.

## HTTP access tokens

REST requests use `Authorization: Bearer <access-token>`. The access token must be an Ed25519 Mesa access token.