API tokens for CI

An API token lets a CI job or script use Suta on its own. It belongs to one workspace and gets its permissions from a role.

Create a token

You need to be an admin.

Go to Settings > API tokens and select Create token.
Enter a Name, such as GitHub Actions, and choose a Role. Pick the role with the least access the job needs; Viewer is the default.
Choose when it Expires: in 30 days, 90 days or 1 year. Never is possible but not recommended.
Create the token, then select Copy token. Suta shows the token only once, so store it in your CI secrets straight away.

Use the token

Set SUTA_TOKEN and run the CLI as usual:

SUTA_TOKEN="$SUTA_CI_TOKEN" suta device list --json

To update devices from a release pipeline, start a rollout and wait for it. The command fails if the rollout pauses, is cancelled or any device fails:

SUTA_TOKEN="$SUTA_CI_TOKEN" suta rollout start --tag site-london --wait

The token replaces any saved login for that command and always uses its own workspace. While it’s set, suta auth login, suta auth logout and suta workspace use are refused.

To call the API directly, send the token as a bearer token:

curl -H "Authorization: Bearer $SUTA_CI_TOKEN" https://app.suta.dev/v1/organizations

What a token can do

A token can do what its role allows, for these tasks only:

List and read devices, rename and tag them, and remove them.
Read monitoring data and logs, and change monitoring settings.
List reported services.
Update the agent on a device, and start and control rollouts.
Read activity, operation history and alerts.

Tokens can’t open terminals, run commands, open remote access, or change settings, people, roles, webhooks or other tokens. Those need a person. Everything a token does is recorded in Activity under the token’s name.

Change or revoke a token

Editing the token’s role changes what it can do straight away. To stop a token, find it in Settings > API tokens, select Revoke, then Revoke token. It stops working on its next request.