Tokens
Managing API keys
Tokens
API keys authenticate programmatic access to the emit.run API. Each key is scoped to a single space.
Creating a Token
- Open a space in the dashboard
- Go to Tokens
- Click Create Token
- Enter a name and select scopes (or use the Worker preset)
- Copy the key immediately — it's shown only once
Choosing Scopes
Pick scopes based on what the token is for:
| Use case | Recommended scopes |
|---|---|
| Producer — app that submits jobs | jobs:create |
| Worker — service that processes jobs | Worker preset (jobs:read, jobs:poll, jobs:ack, jobs:progress, jobs:event, jobs:complete, jobs:fail, jobs:keepalive, jobs:read:progress) |
| Monitor — dashboard or alerting | jobs:read |
| Producer + monitor | jobs:create, jobs:read |
| Third-party client — live job updates only | jobs:read:progress |
| Minimal worker — no progress/events | jobs:poll, jobs:ack, jobs:complete, jobs:fail |
The Worker preset in the token creation dialog selects all the scopes a typical worker needs.
You can also use the shorthand jobs:worker scope which expands to the full worker set during authorization.
All Available Scopes
| Scope | Allows |
|---|---|
jobs:create | Create new jobs in the space |
jobs:read | List jobs, get job details and events |
jobs:poll | Claim pending jobs from the dispatch queue |
jobs:ack | Acknowledge receipt of a polled job |
jobs:progress | Send in-progress updates |
jobs:event | Publish checkpoint events |
jobs:complete | Mark jobs as completed |
jobs:fail | Mark jobs as failed |
jobs:keepalive | Extend a running job's timeout |
jobs:read:progress | Subscribe to single-job WebSocket streams (no space-wide feed) |
jobs:worker | Shorthand — expands to all worker scopes above |
jobs:write | Shorthand — expands to mutation scopes (ack, progress, event, complete, fail, keepalive) |
Security Best Practices
- Store keys in environment variables or a secrets manager — never commit them to source control
- Use separate keys for producers and workers — if a producer key is compromised, your workers keep running
- Use the minimum scopes needed — a producer doesn't need
jobs:poll, a monitor doesn't needjobs:complete - Rotate keys periodically — create a new key, update your services, then delete the old one
- Delete unused keys — every active key is an attack surface