Authentication

Mesa has two credentials for programmatic access:

Private keys: long-lived credentials meant for use in trusted environments (ex. your application server).
Access tokens (JWTs): short-lived tokens meant for use in ephemeral, less-trusted environments (ex. an agent sandbox).

Private keys can mint access tokens, but access tokens cannot be used to mint more credentials. Keep private keys in trusted infrastructure. Use access tokens anywhere you would be uncomfortable leaving a durable secret behind: agent sandboxes, disposable VMs, container sessions, or per-user agent jobs. A private key is never sent to Mesa. The SDK signs access tokens with it locally, and Mesa stores only the matching public key, so minting a token requires no network round-trip.

Basic Usage

Create a key in the Keys section of your organization’s settings in the dashboard. The private key is shown once, so save it to your secrets manager as MESA_PRIVATE_KEY before leaving the page. Construct SDK clients with the private key in your trusted backend:

import { Mesa } from "@mesadev/sdk";

const mesa = new Mesa({ privateKey: process.env.MESA_PRIVATE_KEY });

import os
from mesa_sdk import Mesa

mesa = Mesa(private_key=os.environ["MESA_PRIVATE_KEY"])

Authors

Every commit in Mesa records who made it. Since agents and humans often work on the same repository, a commit can have several authors: for example the user a session belongs to plus the agent doing the edits. Each operation that creates commits takes an ordered authors list. Private-key layout definitions take one too (mesa.fs({ layout, authors })), because writes through the mount become commits.

import { repo } from "@mesadev/sdk";

// The user the work belongs to first, then the agent that did it.
const authors = [
  { name: "Jane Doe", email: "jane@acme.dev" },
  { name: "Acme Agent" }, // email is optional
];

// Writes through an app mount become commits, so the layout definition takes authors.
const fs = await mesa.fs({
  layout: {
    "/workspace": repo("agent-workspace", { mode: "rw", at: { bookmark: "main" } }),
  },
  authors,
}).mount();

// Commit operations take the same list.
await mesa.bookmarks.merge({
  repo: "agent-workspace",
  target: "main",
  source: "agent-draft",
  authors,
});

from mesa_sdk import repo

# The user the work belongs to first, then the agent that did it.
authors = [
    {"name": "Jane Doe", "email": "jane@acme.dev"},
    {"name": "Acme Agent"},  # email is optional
]

# Writes through an app mount become commits, so the layout definition takes authors.
async with mesa.fs(
    layout={"/workspace": repo("agent-workspace", mode="rw", at={"bookmark": "main"})},
    authors=authors,
).mount() as fs:
    ...

# Commit operations take the same list.
await mesa.bookmarks.merge(
    repo="agent-workspace",
    target="main",
    source="agent-draft",
    authors=authors,
)

Mesa preserves the order of the authors list. The first entry is the primary author; the rest are co-authors. In the example above, Jane owns the commits and the agent is credited alongside her.

Minting Access Tokens

Mint a token through a layout definition when you need to hand an access token to another environment, such as a sandbox where the Mesa CLI will run. The layout defines both the mount’s complete visible path tree and the authority of the token: it reaches the repositories the layout declares and nothing else. The token carries its own authors, so anything the sandbox writes is attributed the same way.

import { repo } from "@mesadev/sdk";

const workspace = mesa.fs({
  layout: { "/workspace": repo("agent-workspace", { mode: "rw" }) },
  authors: [{ name: "Mesa Bot", email: "mesa-bot@example.com" }],
  ttl: 60 * 60, // 1 hour; max 4 hours
});
const { token } = await workspace.token();
const layoutJson = JSON.stringify(workspace.layout(), null, 2);

// Copy layoutJson to layout.json in the sandbox, then run:
// MESA_ACCESS_TOKEN=... mesa mount --layout=layout.json --daemonize

import json
from mesa_sdk import repo

workspace = mesa.fs(
    layout={"/workspace": repo("agent-workspace", mode="rw")},
    authors=[{"name": "Mesa Bot", "email": "mesa-bot@example.com"}],
    ttl=60 * 60,  # 1 hour; max 4 hours
)
minted = await workspace.token()
layout_json = json.dumps(workspace.layout(), indent=2)

# Copy layout_json to layout.json in the sandbox, then run:
# MESA_ACCESS_TOKEN=... mesa mount --layout=layout.json --daemonize

The same definition serves the mount. Serialize workspace.layout() with JSON.stringify(...) in TypeScript or json.dumps(...) in Python, write it into the sandbox and start the CLI with mesa mount --layout, and the mount presents exactly the paths the token can reach. A mode of ro grants read only access to that repository; rw grants read and write access. Repositories outside the layout are not accessible.

A layout-scoped token is the only token the SDKs mint. There is no way to export an organization-wide access token: a token always names the repositories it can reach. Code that needs organization-wide authority — creating repositories, administering webhooks — must hold the private key and use new Mesa({ privateKey }), which signs a short-lived organization-scoped token for each request it makes and never hands one out.

See Daytona for a full end-to-end example of this flow with a real sandbox provider. The layout defines the token’s complete repository authority, one permission per repository. A mode of ro grants read-repo; rw grants write-repo, which also allows reads. Repositories outside the layout are not accessible, and a access token can never create repositories. Tokens default to a 15 minute TTL, have a maximum TTL of 4 hours, and are not refreshed automatically. A mount uses one token for its whole lifetime, so choose a TTL that covers the mount’s work. Inside the receiving environment, the Mesa CLI reads the token from MESA_ACCESS_TOKEN. Mounted MesaFS environments and direct REST requests also accept access tokens. TypeScript and Python Mesa clients require a private key and do not accept access tokens.

Getting Started

Concepts

Reference

MesaFS

Usage Patterns

Integrations

Basic Usage

Authors

Minting Access Tokens

​Basic Usage

​Authors

​Minting Access Tokens

Basic Usage

Authors

Minting Access Tokens