How do I create and use API tokens?

TL;DR: API tokens let you run playbooks and integrate with Ballet programmatically. Owners create tokens in Settings → API tokens. Use the token as a Bearer credential in API requests to trigger playbook runs and access workspace resources.

Who this is for

Owners and Builders integrating Ballet with external systems, CI/CD, or custom apps.

How do I create a token?

1. Go to Settings → API tokens.
2. Click Create token.
3. Name the token (e.g. "CI pipeline" or "Webhook handler").
4. Copy the token value — it is shown once.

Only Owners can create new tokens. Builders can view tokens they created.

How do I use a token?

Include the token as a Bearer credential in HTTP requests to the Ballet API:

Authorization: Bearer <your-token>

Use tokens to trigger playbook runs, poll run status, and integrate Ballet into external workflows.

How do I revoke a token?

Delete the token from Settings → API tokens. Revoked tokens stop working immediately.

Security best practices

• Create separate tokens per integration — don't reuse one token everywhere.
• Store tokens as secrets, not in source code.
• Revoke tokens when an integration is decommissioned.

Related articles

• What are the roles and permissions?
• What triggers can start a playbook?
• How do I store credentials with Secrets?