CLI Tokens

CLI tokens (dpl_…) are long-lived, revocable credentials for the deplo CLI, CI pipelines, and any script talking to this API. A token created here authenticates every endpoint in this reference, exactly like a dashboard JWT.

Tokens never expire — they work until revoked. Only a SHA-256 hash is stored server-side, so the raw token is shown exactly once, at creation. The auth middleware recognises the dpl_ prefix and resolves the owner by hash lookup instead of verifying a JWT; see Authentication and the CLI authentication guide.

POST/api/v1/cli-tokensBearer token

Creates a new CLI token. The response is the only time the raw token is ever returned — store it immediately. The name is trimmed and capped at 64 characters; an empty name returns 400 VALIDATION_ERROR.

Field	Type	Description
name	string	Required. A label to recognise the token by, e.g. the machine or pipeline it lives on.

request

curl -X POST https://www.deplo.in/api/v1/cli-tokens \
  -H "Authorization: Bearer $DEPLO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"github-actions"}'

response · 201

{
  "id": "cm5xd6e7f0004njk8x2y3z4a5",
  "name": "github-actions",
  "token": "dpl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2026-08-07T09:24:37.000Z"
}

response · 400

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Token name is required"
  }
}

Shown once

The token value cannot be retrieved again — only its SHA-256 hash is persisted, so even a database leak never exposes usable credentials. If a token is lost, revoke it and create a new one.

GET/api/v1/cli-tokensBearer token

Lists the authenticated user's tokens, newest first — names and usage metadata only, never the token value.

Field	Type	Description
id	string	Token id (cuid) — used to revoke.
name	string	The label given at creation.
lastUsedAt	string \| null	When the token last authenticated a request; null if never used.
createdAt	string	ISO creation timestamp.

request

curl https://www.deplo.in/api/v1/cli-tokens \
  -H "Authorization: Bearer $DEPLO_TOKEN"

response · 200

{
  "tokens": [
    {
      "id": "cm5xd6e7f0004njk8x2y3z4a5",
      "name": "github-actions",
      "lastUsedAt": "2026-08-07T08:59:02.000Z",
      "createdAt": "2026-08-07T09:24:37.000Z"
    },
    {
      "id": "cm5xd0a1b0003njk8m6n7o8p9",
      "name": "work-laptop",
      "lastUsedAt": null,
      "createdAt": "2026-08-01T14:12:20.000Z"
    }
  ]
}

DELETE/api/v1/cli-tokens/:idBearer token

Revokes a token immediately — requests using it fail with 401 from the next call on. Returns 204 with no body, or 404 if the id does not exist or belongs to another user.

request

curl -X DELETE https://www.deplo.in/api/v1/cli-tokens/cm5xd0a1b0003njk8m6n7o8p9 \
  -H "Authorization: Bearer $DEPLO_TOKEN"

response · 204

HTTP/1.1 204 No Content