API tokens & CI deploy

Session cookies are for browsers. For scripts, CLI tools, and CI runners — anything that can’t carry a cookie — Pier issues Bearer API tokens. A token authenticates as the user who created it and inherits that user’s roles, so a CI token can only deploy services its owner could deploy.

Tokens are stored as a SHA-256 hash; the plaintext is shown once at creation and is never recoverable.

Creating a token

From the Account area (or directly against the API, with a session):

Create — POST /api/v1/account/tokens with a name. The response includes the token plaintext exactly once. Copy it now.
List — GET /api/v1/account/tokens. Returns each token’s id, name, prefix, and last_used_at — never the secret.
Revoke — DELETE /api/v1/account/tokens/{id}. Idempotent; revocation takes effect immediately on the next request.

Every issued token carries the pier_npm_ prefix, so a leaked token is recognisable at a glance. Send it in an Authorization: Bearer header:

Authorization: Bearer pier_npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Treat the token like a password. Anyone holding it acts as you, scoped to your roles. Store it in your CI provider’s secret store, never in the repo.

Triggering a deploy from CI

Two authenticated deploy endpoints accept a Bearer token. Both run the same pipeline and return a deployment_id you can poll.

Endpoint	Use when CI knows…
`POST /api/v1/services/{id}/deploy`	the service’s id
`POST /api/v1/projects/{id}/services/{name}/deploy`	the project id and service name

Authorization requires project Editor on the target service (the token owner’s project role). The service must already have its git repo configured. Both endpoints are rate-limited per client IP, since a deploy is an expensive clone-and-build.

The JSON body is optional. Useful fields: commit_sha (recorded for traceability), branch (or ref as an alias), and message. If you omit the branch, Pier uses the service’s configured branch, falling back to main.

curl -X POST https://pier.example.com/api/v1/projects/proj_abc123/services/web/deploy \
  -H "Authorization: Bearer pier_npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "commit_sha": "'"$GIT_COMMIT"'",
        "branch": "main",
        "message": "CI deploy from pipeline #42"
      }'

A successful response returns the deployment id and a status URL:

{
  "ok": true,
  "deployment_id": "d1e2f3...",
  "service_id": "svc_...",
  "status_url": "/api/v1/resources/svc_.../deployments/d1e2f3..."
}

Poll GET /api/v1/resources/{id}/deployments/{deployment_id} until the build reaches a terminal state to make your pipeline wait on the result.

API tokens & CI deploy

Creating a token

Triggering a deploy from CI

Next steps