Create an API token and pick scopes

An API token lets a script, a CI job or another tool talk to SrvYard without your password. It can list servers, queue a deployment, read a log and much more, exactly as you would in the dashboard, but only the parts you allow.

In this article you will create a token with the smallest set of permissions it needs, copy it safely, check that it works with a single curl call, find the full list of operations, and revoke the token when the job is over.

Before you begin#

• A plan with API access. API tokens need a plan that includes the API (Pro and above). On a plan without it the page shows API tokens are not available to you yet and the Create token button is greyed out. See Plans and limits compared.
• A role that allows it. Creating a token needs the tokens:manage permission in the organisation. Every built-in role (Owner, Admin, Manager, Developer and Viewer) has it by default; a custom role can be given it or be denied it. See Roles and permissions.
• A clear job for the token. Decide first what it must do ("deploy one site from GitHub Actions", "read server health for a dashboard"). The token is only as safe as the list of scopes you give it.

1. Open the API tokens page#

Open your account settings from the avatar menu and choose API tokens in the settings sidebar (the page is at /settings/api-tokens).

1. Create token. Opens the creation panel. When you have no tokens yet, the same button sits in the empty state (No API tokens).
2. A token row. Shows the token's name, the last four characters of the secret (srv_…75jA, enough to recognise it, never enough to use it), the organisation it works in, how many Scopes it has, when it was Last used (Never used if it has not been) and when it Expires. An expired token carries a red Expired badge.

The page has two tabs, Tokens and Reference. You will use the second one in step 5.

2. Fill in the New API token panel#

Press Create token. A panel slides in from the right.

1. Name. Up to 80 characters, on one line. Name the token after the job, not the person: GitHub Actions deploy is better than Sam's token, because the name appears in the activity log and in the revoke prompt.
2. Organization. The organisation the token will work in. If you belong to several, only those where you may create tokens (and whose plan has the API) are offered. A token cannot be moved to another organisation later; create a new one instead.
3. Expires. 30 days, 90 days, 1 year, 10 years (default) or Never. Pick the shortest period that suits the job. A short-lived token limits the damage if it leaks, and you can always make a new one.
4. Read-only. A preset that ticks every permission ending in :view: look but never change.
5. Full. A preset that ticks every permission your role holds in that organisation (except tokens:manage, which this page never offers to a token).

Below the presets is the list of scopes, grouped (Organization, Members, Servers, Sites and so on) with a search box. The counter next to Scopes shows how many you have ticked out of how many are available to you. Changing the organisation clears the selection, because the available scopes depend on your role there.

3. Pick the scopes#

A scope is a permission key, the same ones the Roles page uses. servers:view lets the token read servers; sites:manage-deploys lets it deploy, roll back and edit the deploy script. The token can use only the scopes you tick, and only those your role also holds.

1. Read-only has been pressed: every :view scope is ticked, and the counter shows the total. Tick or untick single scopes, or a whole group with the box in its header, to fine-tune the result.
2. Create token. Stays disabled until the token has a name and at least one scope.

Some examples of a sensible choice:

Reading or writing a site's .env needs sites:manage-environment, a deliberately separate scope: a deploy token does not get secrets by accident.

If you pick something your role does not hold, SrvYard refuses with "Your role does not hold" and the names of the scopes.

4. Copy the token#

Press Create token. A dialog titled Copy your new token shows the secret, which starts with srv_, with a copy button.

Press I have copied it when it is safely stored. Then check that it works. In a terminal, put the token in an environment variable and call the endpoint that says who you are:

export SRVYARD_TOKEN="srv_your_token_here"
curl -H "Authorization: Bearer $SRVYARD_TOKEN" \
     -H "Accept: application/json" \
     https://srvyard.example/api/v1/token

Use the base URL shown on your own API tokens page (it is https://<your SrvYard address>/api/v1). The answer names the token, its organisation, its scopes, its expiry and when it was last used. The call needs no scope, so it works for any valid token.

5. Find the operation you need#

The page has a card called Using the API under the token list. It is written for copying.

1. Base URL. Every endpoint lives under /api/v1. Responses are JSON.
2. Authentication. Send the token as Authorization: Bearer srv_... on every request. There is no cookie or session involved.
3. List your servers. A complete curl command to start from. The card also has one for queueing a deployment, which needs the sites:manage-deploys scope.

For everything else, open the Reference tab.

1. Reference. Lists every group of operations (Servers, Sites, Deployments, Webhooks and so on) with the number of operations in each. Choose a group to see its endpoints, the method, the path and the scope each one needs.
2. Search endpoints, scopes. Type a word such as deploy or a scope such as sites:manage-environment to jump to the matching operations.

The Download openapi.json link at the bottom of the list gives you the machine-readable description (OpenAPI 3.1), which you can import into Postman, Insomnia or Bruno to get a ready-made collection. The conventions every endpoint shares are in API conventions.

6. Review and revoke tokens#

Come back to the list from time to time. A token whose Last used says Never used, or a job you have switched off, is a token to remove.

1. Open the actions menu (the three dots) at the end of the row.
2. Choose Revoke.
3. Confirm with Revoke token in the dialog. It says "Anything using this token stops working immediately. This cannot be undone."

The next request made with that token is answered with 401. Revoking is permanent: to restore access, create a new token and update the job. Creating and revoking tokens are both recorded in the activity log, and every change made through a token is logged with the actor token:<name>. See Rotate tokens and review the sign-in log.

Troubleshooting#

• The Create token button is disabled. Either the organisation's plan has no API access, or your role lacks tokens:manage. The alert above the table says which. Ask an owner, or see Plans and limits compared.
• "Your role does not hold: ..." when creating. You ticked a scope your role does not have. Untick it, or ask for a role that includes it.
• 401 unauthenticated. The header is missing, malformed, or the token is not valid. The message says which: "Send your API token as ...", "This API token is not valid. It may have been revoked." or "This API token has expired." (code token_expired).
• 403 with missing_scope. The token is valid but was created without the scope the operation needs. The answer names it in missing_scope. Create a new token with that scope; scopes cannot be edited afterwards.
• 403 with plan_required. The organisation's plan does not include the API (for example after a downgrade). Tokens keep existing but stop working until the plan has API access again.
• I lost the token. It cannot be recovered. Revoke it and create a new one.
• 429 Too many requests. A token may make 60 requests a minute (10 for the heavier operations). See API conventions.

Related#

• API conventions: authentication, pagination, errors and rate limits in detail.
• List servers and sites, trigger actions: your first real calls.
• Rotate tokens and review the sign-in log: keep tokens short-lived and tidy.
• Roles and permissions: where the scope names come from.