Skip to main content
This page lists the exact formats, limits, and precedence rules for Mesa credentials. For the recommended setup, see Authentication.

​
Credentials

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

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

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.