Reference
Applications
Admin API endpoints for creating, changing, enabling, disabling and deleting applications and for group access.
Endpoints under https://acme.sovrain.net/api/v1/apps. Authentication, conventions and the error format are on
Admin API. The protocol settings of an application are on OpenID Connect clients,
SAML configuration and SCIM provisioning. What each setting means:
Application settings.
The application object
{
"slug": "portal",
"name": "Portal",
"type": "oidc",
"status": "active",
"description": "Intranet portal",
"launcher_url": "https://portal.acme.example/",
"access": [
{
"group": { "id": "SuT8oWQLVMPzwYQyhKjm32", "name": "Engineering" },
"role": "editor"
}
]
}
| Field | Type | Notes |
|---|---|---|
slug | string | Identifies the application in the API and in its URLs |
name | string | Shown to members on their home page |
type | string | oidc, saml or scim, in lower case |
status | string | active or disabled, in lower case |
description | string | Left out when not set |
launcher_url | string | Left out when not set. The address the tile on the home page opens. |
access | array | Only on a single application. The groups whose members may sign in, each with its role. role is "" when none is set. |
Application types:
type in requests | Signs people in | Provisions accounts |
|---|---|---|
OIDC | OpenID Connect | no |
SAML | SAML 2.0 | optional SCIM connection |
SCIM | no | SCIM connection |
List applications
GET /api/v1/apps
Scope: apps:read
Response 200, all applications in one page, without access:
{
"items": [
{ "slug": "portal", "name": "Portal", "type": "oidc", "status": "active", "description": "Intranet portal", "launcher_url": "https://portal.acme.example/" },
{ "slug": "expenses", "name": "Expenses", "type": "saml", "status": "active" }
],
"next_cursor": null
}
Get an application
GET /api/v1/apps/{slug}
Scope: apps:read
Response 200: the application object with access.
Errors: 404 not_found, for example Unknown application: slug 'x'.
Create an application
POST /api/v1/apps
Scope: apps:write
| Field | Type | Required | Notes |
|---|---|---|---|
type | string | yes | OIDC, SAML or SCIM, in upper case |
name | string | yes | Must not be blank |
slug | string | yes | 2 to 63 characters from a-z 0-9 -, starting and ending with a letter or digit, unique in the organization, not a reserved word (the same list as organization addresses, for example admin, api, sso, saml, test) |
provisioning | boolean | no | SAML only: also create a SCIM connection. Ignored for OIDC. |
{ "type": "OIDC", "name": "Portal", "slug": "portal" }
Response 201: the application object.
What is created with the application:
| Type | Created |
|---|---|
OIDC | Nothing yet. The OpenID Connect client is created on the first call to /apps/{slug}/oidc. |
SAML | A SAML configuration with the defaults on Application settings and an active RSA-2048 / SHA-256 signing key. With provisioning: true, also a SCIM connection. |
SCIM | A SCIM connection, turned off, with the default mappings |
Errors:
| Status | error | When |
|---|---|---|
| 400 | invalid_request | type missing or not in upper case |
| 422 | refused | Application name must not be blank; Invalid slug 'null': Slug must not be empty.; Invalid slug 'admin': Slug is reserved.; Slug already in use: portal |
Change an application
PATCH /api/v1/apps/{slug}
Scope: apps:write
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | no | Same rule as on create |
slug | string | no | Same rules as on create. Changing it changes the application’s URLs. |
description | string | no | Cannot be set back to none; "" empties it |
launcher_url | string | no | Not checked. Cannot be set back to none; "" empties it. |
A field left out keeps its value.
{ "description": "Intranet portal", "launcher_url": "https://portal.acme.example/" }
Response 200: the application object.
Change the type
PUT /api/v1/apps/{slug}/type
Scope: apps:write
| Field | Type | Required | Notes |
|---|---|---|---|
type | string | yes | SAML or SCIM |
Response 200: the application object. Setting the current type changes nothing.
| Change | Effect |
|---|---|
SAML to SCIM | The SAML configuration is deleted for good: entity ID, signing keys, ACS URLs, SP certificates and attribute mappings. The application’s two-step requirement is turned off. |
SCIM to SAML | A SAML configuration with the defaults is created |
From or to OIDC | Refused |
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | Cannot change application id=4 from OIDC to SAML: an OIDC application keeps its protocol; type missing |
Disable and enable
POST /api/v1/apps/{slug}/disable
POST /api/v1/apps/{slug}/enable
Scope: apps:write
No body. Response 204.
A disabled application refuses every sign-in, and people signed in to it as someone else through a delegation are signed out. SCIM provisioning stops while the application is disabled; no account is deprovisioned because of it.
Delete an application
DELETE /api/v1/apps/{slug}
Scope: apps:delete
No body. Response 204. Delegations to the application are ended first.
Errors: 404 not_found for an unknown application, also on a second call.
Give a group access
PUT /api/v1/apps/{slug}/groups/{groupId}
Scope: apps:write
| Field | Type | Required | Notes |
|---|---|---|---|
role | string | no | Sent to the application as the role claim (OpenID Connect, only with the groups scope) or attribute (SAML). No body, or no role: no role. Not checked. |
Gives the group access, or replaces its role when it already has access.
{ "role": "editor" }
Response 204.
Take access away from a group
DELETE /api/v1/apps/{slug}/groups/{groupId}
Scope: apps:write
No body. Response 204.
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | The group has no access: Group 5 has no access to application 4 |