Sovrain
  1. Documentation
  2. Identity provider
  3. For developers
  4. Admin API

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"
    }
  ]
}
FieldTypeNotes
slugstringIdentifies the application in the API and in its URLs
namestringShown to members on their home page
typestringoidc, saml or scim, in lower case
statusstringactive or disabled, in lower case
descriptionstringLeft out when not set
launcher_urlstringLeft out when not set. The address the tile on the home page opens.
accessarrayOnly 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 requestsSigns people inProvisions accounts
OIDCOpenID Connectno
SAMLSAML 2.0optional SCIM connection
SCIMnoSCIM 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

FieldTypeRequiredNotes
typestringyesOIDC, SAML or SCIM, in upper case
namestringyesMust not be blank
slugstringyes2 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)
provisioningbooleannoSAML 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:

TypeCreated
OIDCNothing yet. The OpenID Connect client is created on the first call to /apps/{slug}/oidc.
SAMLA SAML configuration with the defaults on Application settings and an active RSA-2048 / SHA-256 signing key. With provisioning: true, also a SCIM connection.
SCIMA SCIM connection, turned off, with the default mappings

Errors:

StatuserrorWhen
400invalid_requesttype missing or not in upper case
422refusedApplication 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

FieldTypeRequiredNotes
namestringnoSame rule as on create
slugstringnoSame rules as on create. Changing it changes the application’s URLs.
descriptionstringnoCannot be set back to none; "" empties it
launcher_urlstringnoNot 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

FieldTypeRequiredNotes
typestringyesSAML or SCIM

Response 200: the application object. Setting the current type changes nothing.

ChangeEffect
SAML to SCIMThe 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 SAMLA SAML configuration with the defaults is created
From or to OIDCRefused

Errors:

StatuserrorWhen
422refusedCannot 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

FieldTypeRequiredNotes
rolestringnoSent 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:

StatuserrorWhen
422refusedThe group has no access: Group 5 has no access to application 4