API Tokens

API tokens (sk_live_...) let agents, CI pipelines, and scripts authenticate without interactive login.

Creating a token

Via the dashboard: Navigate to Tokens → New Token. Enter a name, select scopes, and copy the token on creation.

Via the CLI:

deplo tokens create "CI Deploy" --scopes deploy
# ✔ Token created (shown once):
# sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Via the REST API:

curl -X POST https://api.deplo.sh/workspaces/<workspaceId>/access-tokens \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI Deploy", "scopes": ["deploy"] }'

Caution: The raw token value is shown only once at creation time. Store it immediately in your secrets manager. It cannot be retrieved again.

Token scopes

Use the minimum required scope. A deploy-only token cannot delete projects or manage members even if stolen.

Workspace vs project scope

Tokens can be created at two levels:

Create a project-scoped token:

deplo tokens create "Agent Token" --scopes deploy --project proj_abc123

Token expiry

Tokens are permanent by default. Optionally set an expiry date:

deplo tokens create "Temp Token" --expires 2026-12-31

Listing tokens

deplo tokens list

The raw token value is never shown again — only the prefix (sk_live_xxxx…), name, scopes, last-used date, and expiry.

Revoking a token

Via the dashboard: Navigate to Tokens → click the trash icon on the token.

Via the CLI:

deplo tokens revoke tok_abc123 --yes

Via the REST API:

curl -X DELETE https://api.deplo.sh/workspaces/<workspaceId>/access-tokens/<tokenId> \
  -H "Authorization: Bearer <token>"

Revocation is immediate. Any in-flight requests using the token will fail with 401.

Token limits by plan

Security recommendations

• Use project-scoped tokens for agents that only need to access a single project
• Rotate tokens regularly for long-running services
• Store tokens in your CI/CD secret store — never commit them to source control
• Use --expires for temporary integrations

What's next?

• Authentication — overview of all auth methods (JWT + tokens)
• Quickstart — deploy your first file using a token
• REST API — use tokens with the HTTP API directly
• Billing & Plans — token limits by plan