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:
| Choice | Effect |
|---|---|
| Nobody | No tokens can be made, and every existing token stops working. This is the default |
| Administrators | Only administrators can make and use tokens |
| Everyone | Anyone 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
- Under Your tokens, give it a Name: what will use it, so you know which to revoke later. For example
Release pipeline. - Choose how long it Lasts: 30 days, 90 days (the default), A year or Until revoked.
- Press Make a token.
- 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:
| What | Endpoints |
|---|---|
| Who the token acts as | GET /api/me |
| The resource list | GET /api/resources |
| Start, stop, reboot, keep on, turn on, end a keep-on, drop, re-add and set tags | POST /api/actions |
| Server groups: list, start, stop, turn on until | GET /api/groups, POST /api/groups/<id>/start, /stop, /on |
| Bookings: list, make, cancel | GET /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:
| Column | What it shows |
|---|---|
| Name | The name, and the first characters of the token, for example dlg_AbC12x… |
| Made | When it was made |
| Last used | When it was last used, and from which address. Updated at most every 5 minutes. Never if unused |
| Valid | Until 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
| Status | Message | Meaning |
|---|---|---|
| 401 | Invalid or expired API token | Wrong, revoked or expired token |
| 401 | API tokens are switched off | Who may have tokens is Nobody |
| 403 | API tokens are for administrators only | The owner is no longer allowed tokens under the current choice |
| 403 | API tokens cannot be used for this; sign in to the web UI | The 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.
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.