How do I authenticate with the Ballet API?
TL;DR: Authenticate every API request with a workspace API token sent as a Bearer credential: Authorization: Bearer mt_live_…. Owners mint tokens in Settings → API tokens; the value is shown once. Store it as a secret (for example BALLET_API_TOKEN) and use a separate token per integration so you can revoke without breaking everything.
Who this is for
Developers making authenticated calls to the Ballet REST API or MCP endpoint.
How do I create a token?
- Go to Settings → API tokens.
- Click Create token and name it for its integration (for example "CI pipeline").
- Copy the value immediately — it is shown only once. Tokens use the
mt_live_…prefix.
Only Owners can create tokens; Builders can view tokens they created.
How do I send the token?
Pass it in the Authorization header on every request:
curl https://app.ballet.dev/api/playbooks \
-H "Authorization: Bearer $BALLET_API_TOKEN"
Set the token from your environment rather than hardcoding it:
const token = process.env.BALLET_API_TOKEN;
const res = await fetch("https://app.ballet.dev/api/playbooks", {
headers: { Authorization: `Bearer ${token}` },
});
What can a token do?
A token acts as your workspace and is scoped to it. Use it to list and run playbooks, poll run status and step results, and call the management surface. The MCP endpoint also accepts the same token as a Bearer credential (see The MCP endpoint).
Security best practices
- One token per integration — never reuse a single token everywhere.
- Store tokens in a secret manager or environment variable, never in source control.
- Rotate by creating a new token, switching the integration over, then deleting the old one.
- Revoke immediately from Settings → API tokens when an integration is decommissioned — revoked tokens stop working at once.