Loading…
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?
- Go to Settings → API tokens.
- Click Create token.
- Name the token (e.g. "CI pipeline" or "Webhook handler").
- 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.