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.
List APIs and roles
Section titled “List APIs and roles”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.
Create an API
Section titled “Create an API”| 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 an API
Section titled “Delete an API”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” |
Add a permission
Section titled “Add a permission”| 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 a permission
Section titled “Delete a permission”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.
Create a role
Section titled “Create a role”| 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” |
Change a role
Section titled “Change a role”The answer is the role. Tokens issued from then on carry the change; tokens already out keep what they had until they expire.
Delete a role
Section titled “Delete a role”Answers 204, or 404.
Giving roles
Section titled “Giving roles”- To users: Set a user’s roles.
- To machine clients: Set a client’s roles.