API tokens and API

#Create a token

Open Settings > API tokens and create one. Creating a token asks you to confirm it is you. Choose:

The token is shown once. It starts with dk_. Dockify stores only a hash of it, and shows the first few characters afterwards so you can tell tokens apart. You can have up to 25 active tokens. Revoke one at any time.

#What a token can do

A token acts with the lower of its scope and the role of the person who made it, and only on the projects it was given. It can never confirm it is you, so it can never reach an elevated route unless that exact power was granted when it was made.

With the admin scope and the env:write grant, a token can also write, apply and roll back variables, for plain values only. It can never write a secret value or a key such as NODE_OPTIONS that changes what runs.

A token's last use and address are kept on the token, and every call that changes something writes an activity entry; a read does not. Admins can see every member's tokens, so a leaked one can be found and revoked.

A password change leaves your tokens working, so check Settings > API tokens if the change was because someone else got in. A password reset, from an emailed link or with dockify admin reset-password, revokes all of them. Anything that used one needs a new token.

#Calling the API

The api lives on your dashboard's hostname under /api/v1, in direct and tunnel mode alike. Send the token as a bearer.

curl -fsS https://dockify.example.com/api/v1/projects \
  -H "Authorization: Bearer $DOCKIFY_TOKEN"

Requests and responses are JSON. Mutations with no body take {}.

#Deploy an app

curl -fsS -X POST https://dockify.example.com/api/v1/apps/$APP_ID/deploy \
  -H "Authorization: Bearer $DOCKIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

It answers 202 with { "deploymentId": "..." }. If a deploy of that app is already in flight you get 409.

#Follow a deployment

curl -fsS https://dockify.example.com/api/v1/deployments/$DEPLOYMENT_ID \
  -H "Authorization: Bearer $DOCKIFY_TOKEN"

Poll until the status is ready, failed or cancelled. For the log, GET /api/v1/deployments/:id/logs returns a page of lines, and /logs/stream is a server-sent event stream with line, done and error events that resumes from Last-Event-ID.

#Useful routes

Every route is defined once, with its request and response schemas, in packages/contracts/src/endpoints.ts. That file is the reference.

#Errors

Errors are JSON with a message and often a code:

{ "error": "This deployment is already the one serving", "code": "ALREADY_CURRENT" }

A rate-limited request carries retryAfter in seconds. A variables apply that lost a race answers 409 with the current version to rebase on.

#In GitHub Actions

Store the token as a repository secret and call the deploy route after your tests pass. Use it when you want a deploy only after CI is green.

#Command line

The dockify command the installer puts on the server is something else: it runs the stack, updates and account rescue on the server itself. See The dockify command.

#What can go wrong

• 401. The token is wrong, expired or revoked.
• 403. The scope or the token's projects do not cover this route, or the role of the person who made it is too low.
• The route needs you to confirm it is you. Tokens cannot. Do it in the dashboard, or mint a token with the grant the route accepts.