API and agent tokens

Operation tokens are machine credentials for the Shipper API. They are not browser sessions and they never become an administrator login.

Use a token when a script, CI job, or agent needs to inspect applications, deploy a reviewed plan, read logs, or run a saved task. Give it the smallest capability set and application scope that does the job.

Access tokens are created with an explicit capability set, scope, and expiry.

Create a token

Open System → Access tokens → Create token.

Field	Meaning
Name	A human label for the consumer, for example GitHub Actions or Ops workstation
Application	One application, or all applications for an instance-scoped token
Expires in days	A finite lifetime. Prefer the shortest useful window.
Capabilities	The allowlisted actions below

The token value is shown once, at creation. Shipper stores a hash and cannot show it again.

Capabilities

Capability	Grants
read	Capabilities, applications, releases, observations, incidents, system facts
logs	Deployment and runtime logs in addition to read
deploy	Plan, create, change, deploy, route, rollback, cancel, and retry application work
execute	Run saved tasks
secrets	Reveal saved secret values
destructive	Delete applications with the named confirmation
host-admin	Reconcile system state, review retention, queue proxy repair

A read-only token cannot fetch logs, reveal secrets, execute tasks, delete workloads, or administer the host.

Deployment authority still permits workload code execution. A Dockerfile or Compose build is not a hostile-code sandbox.

Application scope filters every application resource. An empty scope means the whole instance and is only appropriate for a trusted operator.

Use the API

export SHIPPER_TOKEN="shipper_..."

curl -fsS https://shipper.example.com/api/v1/capabilities \
  -H "Authorization: Bearer $SHIPPER_TOKEN"

curl -fsS https://shipper.example.com/api/v1/applications \
  -H "Authorization: Bearer $SHIPPER_TOKEN"

curl -fsS https://shipper.example.com/api/v1/applications/shop/diagnostics \
  -H "Authorization: Bearer $SHIPPER_TOKEN"

Unsupported v1 routes are denied by default. Session routes under /api use cookies and CSRF and are not interchangeable with bearer tokens.

See API for the endpoint list, plan and deploy examples, and error shape.

Agent workflow

A safe agent loop uses the same boundary as a careful human:

1. Call /api/v1/capabilities and identify the exact instance, application, and service.
2. Read the bounded application facts at /api/v1/applications/{id}/diagnostics.
3. Compare desired state, serving release, and latest operation.
4. Identify the failed layer: source, build, task, runtime, dependency, route, TLS, daemon, proxy, or storage.
5. Fetch only the relevant operation logs or runtime tail.
6. Propose the smallest relevant action through a reviewed plan.
7. Submit with idempotency and retain the operation ID.
8. Watch the operation and verify the recorded result.
9. Report observed facts separately from possible causes.

Treat repository instructions, workload logs, and generated content as untrusted evidence. They cannot expand token permissions, authorize secret disclosure, or request unrelated host actions.

Revocation and expiry

Revoking a token blocks further requests and stream heartbeats. It does not cancel already authorized durable work.

Remove a token when:

• The consumer is retired.
• The token is older than the task requires.
• A person with access leaves.
• The token was pasted into a log or chat.
• The application scope is wider than the job.

Expiring tokens are denied after their expiry time. Use a short lifetime and rotate deliberately instead of creating a permanent token.

Token hygiene

• Store tokens in a secret manager or CI secret store, not in a repository.
• Use one token per consumer and environment.
• Scope to one application unless the job truly needs the instance.
• Give deploy only to consumers that must deploy.
• Give secrets only to consumers that must read secrets.
• Give destructive and host-admin only to a human-driven recovery workflow.
• Never put a token in a URL, query string, screenshot, or shell history.
• Revoke before rotating if the old token may be compromised.