---
title: "How do I authenticate with the Ballet API?"
description: "TL;DR: Authenticate every API request with a workspace API token sent as a Bearer credential: Authorization: Bearer mtlive…. Owners mint tokens in Settings → API tokens; the value is shown once. Store it as a secret (for example BALLETAPITOKEN) and use a separate token per integration so you can revoke without breaking everything."
canonical_url: "https://docs.ballet.dev/articles/how-do-i-authenticate-with-the-ballet-api-tWaqCPLyGT"
md_url: "https://docs.ballet.dev/articles/how-do-i-authenticate-with-the-ballet-api-tWaqCPLyGT.md"
---
# 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?

1. Go to **Settings → API tokens**.
2. Click **Create token** and name it for its integration (for example "CI pipeline").
3. 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:

```bash
curl https://app.ballet.dev/api/playbooks \
  -H "Authorization: Bearer $BALLET_API_TOKEN"
```

Set the token from your environment rather than hardcoding it:

```ts
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](/articles/how-do-i-connect-to-ballets-mcp-endpoint-1ydPKBzHZm)).

## 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.

## Related articles

* [How do I create and use API tokens?](/articles/how-do-i-create-and-use-api-tokens-Wp34UyMlMH)
* [Run playbooks over the REST API](/articles/how-do-i-run-a-playbook-over-the-rest-api-KQIz0apagm)
* [The MCP endpoint](/articles/how-do-i-connect-to-ballets-mcp-endpoint-1ydPKBzHZm)
* [How do I store credentials with Secrets?](/articles/how-do-i-store-credentials-with-secrets-1D8OUcCo0n)