Skip to main content

API tokens

API tokens are for scripts and pipelines: a test run that starts its environment first and stops it afterwards, or a job that keeps a machine on overnight. A token acts as the person who made it, with their access, and reaches the everyday actions only.

Who may have tokens​

Tokens are off until an administrator turns them on. Open the API tokens page (see below). Administrators see Who may have tokens at the top:

ChoiceEffect
NobodyNo tokens can be made, and every existing token stops working. This is the default
AdministratorsOnly administrators can make and use tokens
EveryoneAnyone who signs in can make and use tokens

The choice is saved as soon as you click it. Switching to Nobody stops every token at once; switching back on brings back the ones that were not revoked and have not expired.

Finding the page​

Open My account from the user menu (your name, top right). Under Also yours, API tokens opens the page and shows how many valid tokens you have. The page's address is #/tokens.

Making a token​

  1. Under Your tokens, give it a Name: what will use it, so you know which to revoke later. For example Release pipeline.
  2. Choose how long it Lasts: 30 days, 90 days (the default), A year or Until revoked.
  3. Press Make a token.
  4. Copy the token straight away. It is shown once: "Copy it now: it is not shown again." Delegaris keeps only a hash of it.

The page also shows a ready-made curl example with the token in it.

Tokens start with dlg_. Each person can have up to 20 tokens that are not revoked. A token can only be made while signed in to the web UI; a token cannot make another token.

Using a token​

Send it as a bearer token in the Authorization header:

curl -H "Authorization: Bearer dlg_your-token-here" \
https://delegaris.example.com/api/resources

Calls made with a token need no CSRF header. For the endpoints and examples, see the API reference.

What a token can reach​

A token reaches the everyday actions and nothing else:

WhatEndpoints
Who the token acts asGET /api/me
The resource listGET /api/resources
Start, stop, reboot, keep on, turn on, end a keep-on, drop, re-add and set tagsPOST /api/actions
Server groups: list, start, stop, turn on untilGET /api/groups, POST /api/groups/<id>/start, /stop, /on
Bookings: list, make, cancelGET /api/bookings, POST /api/bookings, DELETE /api/bookings/<id>

Anything else, including settings, access rules, accounts, approvals, reports, activity, sign-in and tokens themselves, is refused with "API tokens cannot be used for this; sign in to the web UI".

What a token is allowed to do​

A token acts as the person who made it:

  • Their access as the directory last described them. Their groups are the ones reported at their most recent sign-in. If their group membership changes, the token follows it after they next sign in.
  • Access rules apply exactly as in the browser. A token sees and acts on only what its owner's rules allow.
  • Approvals apply. An action that needs approval is sent for approval, and the result says so. See Approvals.
  • Protected resources apply. See Protected resources.
  • Roles given in the web UI (administrator, auditor) count as they are now.

Your tokens​

The Your tokens table lists your tokens:

ColumnWhat it shows
NameThe name, and the first characters of the token, for example dlg_AbC12x…
MadeWhen it was made
Last usedWhen it was last used, and from which address. Updated at most every 5 minutes. Never if unused
ValidUntil a date, Until revoked, Expired or Revoked

Revoke stops a token straight away. Anything using it then gets "Invalid or expired API token".

Everyone's tokens​

Administrators also see Everyone's tokens, with a Whose column, and can revoke any of them.

Errors​

StatusMessageMeaning
401Invalid or expired API tokenWrong, revoked or expired token
401API tokens are switched offWho may have tokens is Nobody
403API tokens are for administrators onlyThe owner is no longer allowed tokens under the current choice
403API tokens cannot be used for this; sign in to the web UIThe endpoint is not one a token can reach

Audit​

  • Making and revoking a token, and changing who may have tokens, are recorded in the activity log.
  • Actions on resources made with a token are recorded under the owner's name, with "with API token name" in the detail.
tip

Make one token per pipeline, with a name that says which, and the shortest lifetime that works. Then a leaked token can be revoked without breaking anything else.

Next steps​