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://api.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://api.ballet.dev/api/playbooks", {
headers: { Authorization: `Bearer ${token}` },
});
The API is served from api.ballet.dev. app.ballet.dev serves Ballet Studio and returns the app's HTML for API paths rather than an error, so a request sent there appears to succeed while returning no data.
What can a token do?
A token acts as your workspace and is scoped to it, with the role it was minted for. Use it to list and run playbooks, poll run status and step results, and call the management surface.
The same token also authenticates the MCP endpoint — send it as a Bearer credential when your MCP client cannot complete a browser OAuth flow. Interactive clients should prefer OAuth, which issues short-lived tokens and needs nothing pasted.
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, on both REST and MCP.