Skip to content

APIs and roles

An API is a server that takes access tokens. Its audience is the aud of the tokens made for it, and its permissions are what may be done with it, such as links:write. A role is a set of permissions; users and machine clients are given roles, and their access tokens carry the roles and the permissions of the API they are for. See Roles and permissions.

Every environment also has the built-in account API, which belongs to no app: it is what a signed-in user calls to change their own account. It cannot be deleted and needs no permissions.

GET/v1/environments/:id/apisviewer

The environment’s APIs with their permissions, and its roles. This is also the only listing of roles. ?app_id= keeps one app’s, together with what belongs to no app (the account API and group-wide roles).

{
"apis": [
{
"id": "…",
"app_id": "…",
"audience": "links-api",
"name": "Links",
"builtin": false,
"permissions": [{ "id": "…", "name": "links:write" }]
}
],
"roles": [{ "id": "…", "app_id": "…", "name": "editor", "requires_aal2": false, "permission_ids": ["…"] }]
}

builtin is true for the account API.

POST/v1/environments/:id/apisdeveloper
Field Type Meaning
audience string 1 to 100 letters, digits and - _ . : /. Unique in the environment.
name string 1 to 80 characters.
app_id uuid Optional when the group has one app.
POST /v1/environments/{env}/apis
{ "audience": "links-api", "name": "Links" }
201
{ "id": "…", "app_id": "…", "audience": "links-api", "name": "Links", "permissions": [] }

An audience stays with the app it was made for, even after the API or the app is deleted: that app’s servers may still take tokens naming it, so only that app may use it again.

Status code When
400 bad_request “audience is letters, digits and - _ . : /”
409 conflict “this audience is taken”, “this audience belonged to another app: tokens for it may still be trusted there”
422 invalid_entity name missing or too long.
DELETE/v1/environments/:id/apis/:apideveloper

Answers 204, or 404. Its audience is kept for its app.

Status code When
409 conflict “the account API is built in”, “a client still uses this API as its default”
POST/v1/environments/:id/apis/:api/permissionsdeveloper
Field Type Meaning
name string Letters, digits and - _ . : /, such as links:write. Unique within the API.
POST /v1/environments/{env}/apis/{api}/permissions
{ "name": "links:write" }
201
{ "id": "…", "name": "links:write" }
Status code When
400 bad_request “a permission looks like links:write”
404 not_found Unknown API.
409 conflict “this permission exists”
DELETE/v1/environments/:id/permissions/:permissiondeveloper

Answers 204, or 404.

A role belongs to an app, and then counts in tokens for that app’s APIs, or to no app (group-wide), and then counts in tokens for every app’s APIs in the group. Permissions are always those of the token’s own API.

POST/v1/environments/:id/rolesadmin with permissions, else developer
Field Type Meaning
name string Letters, digits and - _ . :. Unique per app, and among the group-wide roles.
app_id uuid or null The app. Leave it out, or send null, for a group-wide role. It cannot change later.
requires_aal2 boolean Default false. When true, the role counts only in a session with two steps (acr aal2); otherwise it is left out of the token.
permission_ids uuid[] Default []. A role with permissions takes the admin role to create.
POST /v1/environments/{env}/roles
{ "name": "editor", "app_id": "…", "permission_ids": ["…", "…"] }
201
{ "id": "…", "app_id": "…", "name": "editor", "requires_aal2": false, "permission_ids": ["…", "…"] }
Status code When
400 bad_request “a role name is letters, digits and - _ . :”, “permission_ids names an unknown permission”
409 conflict “this role exists”
PATCH/v1/environments/:id/roles/:roleadmin

The answer is the role. Tokens issued from then on carry the change; tokens already out keep what they had until they expire.

DELETE/v1/environments/:id/roles/:roledeveloper

Answers 204, or 404.