Tokens
A token is a scoped, revocable deploy credential. Use tokens to grant temporary deploy access without sharing your API key.
Available via CLI, SDK, and API.
Shown only once
When you create a token, the response contains the full secret — a deploy-{32 hex} string. Copy it immediately. It is shown once and cannot be retrieved later. List endpoints return only a short identifier; the full secret is never returned again.
If you lose a token, revoke it and create a new one.
Properties
| Property | Description |
|---|---|
token |
Short identifier for management (full secret returned only on create) |
labels |
Labels for the token, which every deployment it uploads gets too (e.g. project:acme, env:staging) |
created |
Creation timestamp |
expires |
Expiration time (optional, set via TTL in seconds at creation) |
used |
When the token was last used |
ip |
If set, the token may only be used from this IP. Captured automatically from the first request that uses it |
Labels on what a token uploads
Every deployment a token uploads gets the token's labels. Labels sent with the upload are added after them, and a label that's on both is kept once. A token labeled project:acme that uploads with env:preview makes a deployment labeled project:acme and env:preview.
The token's labels count toward a deployment's 10, so a token with 8 labels leaves room for 2 more at upload. After the upload they're ordinary labels, and your API key can change them like any other.
Tokens vs API Keys
| API Key | Token | |
|---|---|---|
| Lifetime | Persistent | Expires (optional TTL) |
| Usage | Unlimited | Reusable until expiry or revocation |
| Scope | Full account access | Deploy only |
| Per account | One | Unlimited |
| IP lock | No | Optional |
There is one credential slot, so there is no precedence to reason about. You pass one value — --token, SHIP_TOKEN, or the token constructor option — and the platform classifies it by its prefix. See API Key.
Use Cases
CI/CD. Create a token with a short TTL for each pipeline run. It expires automatically.
Integrations. Give each tool that deploys on your behalf its own token instead of your API key. Set a TTL to expire it, or revoke it any time.
Operations
| Operation | Description |
|---|---|
| Create | Generate a new token with optional TTL and labels |
| List | All active tokens on your account |
| Delete | Revoke a token |