When systems outside of the Releng API need to make API calls, they can do so using a token. Tokens are opaque strings (actually JSON Web Tokens) which are provided in the Authorization header:
GET /some/resource HTTP/1.1 Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpZCI6OSwidiI6MX0.pVmY1aTyASlf24h4acVOiqNgt85mfViXDTvxLsY_qdY
Each token permits a limited set of permissions, specified when the token is issued.
If you have adequate permissions, the API home page will display a link to manage tokens. On this page, you can issue, examine, and revoke user and permanent tokens, depending on your permissions.
User tokens which grant permissions that the user no longer posesses are automatically disabled. In the UI, they are indicated with a "(DISABLED)" tag. Such tokens are not usable for authentication. If the user's permissions change back (for example, if the user was misconfigured temporarily), the token will be re-enabled.
In order to issue a new token, the caller must have the appropriate issuing permission (see below) as well as all permissions in the requested token. The string form of the token is only produced when the token is initially issued; thereafter it is referred to only by ID, if at all.
Some tokens do not have IDs. These tokens cannot be managed after they are issued. Fortunately, all such tokens have limited lifetimes.
There are several types of tokens available. Depending on your permissions, some or all of these may be unavailable to you.
To issue a token, supply all of the required attributes except
A permanent token is issued by an administrator and never expires -- even if that administrator's account is terminated. Permanent tokens are used for authentication of other, internal systems to RelengAPI.
A permanent token has attributes
A user token is issued by a non-administrative user, and lasts as long as that user's account is still active. User tokens are very similar to GitHub's "personal access tokens" -- they entitle the bearer to act as the user, with some subset of the user's permissions.
A user token has attributes
user attribute is filled in automatically when the token is issued.
A request to issue a user token must use an authentication mechanism associated with a user (a browser session or another user token).
A temporary token has a limited lifetime, and can have a small amount of metadata attached. Temporary tokens are used to give short-term, narrowly-focused permissions to other systems. For example, a build job might use a temporary token to record its results, with the permissions of the token limited to writing results for its build ID.
A temporary token has attributes
not_before attribute should be omitted when requesting a new token; the API will set it to the current time.
A temporary token cannot be valid beyond
RELENGAPI_TMP_TOKEN_MAX_LIFETIME seconds in the future; see Token Authentication.
Permission to manipulate tokens are controlled by a number of permissions:
base.tokens.prm.view -- view all permanent tokens
base.tokens.prm.issue -- issue a permanent token
base.tokens.prm.revoke -- revoke a permanent token
base.tokens.usr.view.all -- view all user tokens
base.tokens.usr.view.my -- view my user tokens
base.tokens.usr.issue -- issue a user token
base.tokens.usr.revoke.all -- revoke any user token
base.tokens.usr.revoke.my -- revoke a user token issued by me
base.tokens.tmp.issue -- issue a temporary token.
A token granting the bearer a limited set of permissions.
In all cases except creating a new token, the
token attribute is empty.
There is no way to recover a lost token string except for revoking and
re-issuing the token.
These API calls can be used to manipulate tokens, given sufficient permissions.
Issue a new token. The body should not include a
but should include a
typ and the necessary fields for that type. The
response will contain both
id. You must have permission
to issue the given token type.
Get a list of all unlimited-duration tokens the user has permisison to see.
?typ=.., limit to tokens of that type.
Note that the response does not include the actual token strings. Such strings are only revealed when creating a new token.
Revoke an authentication token, identified by its ID.
The caller must have permission to revoke this type of token; if
that is a
.my permission, then the user email must match.
The response status is 204 on success. Revoking an already-revoked token returns 403.
Get a token, identified by its
Get a token, specified by the token key given in the request body (this avoids embedding a token in a URL, where it might be logged).
The caller must have permission to view this type of token, unless the token is limited-duration (in which case the API is simply decoding the JSON web token anyway).