Keys

Every request to https://data.shipmantis.com carries a project key. The key says which project the request is for and what it may do. There are two kinds, and they always come as a pair.

A project starts with one pair, made with the project. Each machine that runs init against that project later gets its own pair.

Which key a request needsCopy Anchor Link

A publishable key sent where the secret key is needed is refused with 403, before the request does anything.

Sending a keyCopy Anchor Link

The SDK sends the key for you. Pass the one that fits where the code runs:

import { createClient } from "@shipmantis/sdk";
import schema from "../mantis/schema";

export const mantis = createClient({
  url: process.env.MANTIS_URL!,
  key: process.env.MANTIS_SECRET_KEY!,
  schema,
});

Without the SDK, send the key as a bearer token. Mantis-Branch picks a branch; leave it out for main.

curl https://data.shipmantis.com/v1/schema \
  -H "Authorization: Bearer $MANTIS_SECRET_KEY" \
  -H "Mantis-Branch: try-tags"

A live query sends the key once, when its connection opens, and the branch as a connection parameter. The SDK does both.

A pair per machineCopy Anchor Link

Every key has a name, and the two keys of a pair share it. The first pair has no name; the dashboard lists it as Made with the project.

Running init on a project that already has keys makes a new pair named after the machine, like work-laptop, mantis init, and writes it to that folder's .env.local. The keys on every other machine keep working.

To make a pair yourself, open the project in the dashboard, type a name under New key pair (up to 64 characters), and press Add. A pair for your production server, one for CI and one per teammate's laptop means any one of them can be reset or deleted without touching the others.

Shown onceCopy Anchor Link

Mantis keeps a SHA-256 hash of each key, never the key itself. The full key is shown exactly once: in the init output and .env.local, or in the dashboard right after you add or reset it. After that the dashboard shows only its first 16 characters, like mk_secret_BS5QFt…, to tell keys apart.

A lost key can't be recovered. Reset it, or add a new pair.

Reset or deleteCopy Anchor Link

Both are on the project's page in the dashboard, next to each key, and both ask before they do anything.

Neither can be undone. To get a deleted key's place back, add a new pair.

Deleting every key leaves the project unreachable from code until you add a new pair. The dashboard and your data are not affected.

Rotating without downtimeCopy Anchor Link

A reset stops the old key before you have put the new one in place. To swap a key on a running service without a single refused request, overlap them:

If a key leaksCopy Anchor Link

A leaked secret key can read and change every row, change the schema and rewind. Treat it as an incident.

A leaked publishable key is expected: every visitor to your site has it. What protects your data is the access rules. Reset it only if you want to cut off a copy of your app that uses it.

When a reset or delete takes effectCopy Anchor Link

Every HTTP request looks its key up again, so the next request with a reset or deleted key is refused.

A live query checks its key when its connection opens. A connection that is already open keeps receiving updates until it closes, for example when the page is reloaded; it can't reconnect with the old key.

Keys and branchesCopy Anchor Link

Every key belongs to its project's main. There are no branch keys: any key can reach any branch by naming it, through Mantis-Branch, --branch, MANTIS_BRANCH or createClient({ branch }). A request for a branch that doesn't exist is refused with 404.

Keys and your agentCopy Anchor Link

The MCP server and the CLI read MANTIS_SECRET_KEY from .env.local, then .env. The agent works with the secret key, so its queries skip the rules; a risky change on main still waits for a person in the dashboard.

init adds .env.local to .gitignore, and the instructions it writes for the agent tell it never to print or commit the key. If it ever does, reset the key.

ErrorsCopy Anchor Link

The SDK throws a MantisError with the status and the message:

import { MantisError } from "@shipmantis/sdk";

try {
  await mantis.from("todos").select();
} catch (error) {
  if (error instanceof MantisError && error.status === 401) {
    // The key is missing, mistyped, reset or deleted.
  }
  throw error;
}