Sovrain
  1. Documentation
  2. Identity provider
  3. For developers

How-to guide

Offboard people with the Admin API

Suspend people who leave, remove their accounts later and take away part of someone's access, from a script.

This guide stops access for people who leave, from a script, for example one fed by your HR system. Suspending blocks sign-in at once and can be undone; removing is final. The Admin API lives at https://acme.sovrain.net/api/v1 and takes and returns JSON.

Before you start

  • Get an Admin API token with the scopes users:read and users:write. Add users:delete only if the script removes accounts, and groups:write only if it takes people out of groups.
  • Have the token approved by an admin who stays. Suspending or removing the admin who approved it ends the grant, and the script’s next call answers 401 invalid_token.

In the examples, $TOKEN holds the access token:

API=https://acme.sovrain.net/api/v1
AUTH="Authorization: Bearer $TOKEN"

Suspend the person

  1. Find the person and note their id:

    curl -G "$API/users" -H "$AUTH" --data-urlencode "q=anna@acme.example"
    

    q matches part of the login, the email or the name, so the answer can list more than one person. Take the item whose login or email is exactly the one you looked for. If no item matches, the person is not in the organization; removed people are never listed.

  2. Suspend them:

    curl -X POST "$API/users/Jt4mQ8bXz2PwRk6NcY3hVa/suspend" -H "$AUTH"
    

    Sovrain answers 204, also when the person was already suspended, so the call is safe to repeat. What suspending ends is listed in Users › Suspend a user.

    If the answer is 422 with You cannot suspend or remove the last owner of this organization., the person is the only active owner. An admin must first make someone else an owner.

  3. Check the result:

    curl "$API/users/Jt4mQ8bXz2PwRk6NcY3hVa" -H "$AUTH"
    

    The answer has "status": "suspended". To list everyone who is suspended, call GET $API/users?status=suspended.

What the person’s applications do next:

  • Applications provisioned over SCIM deactivate or delete the account after a 3-minute wait, as their Deprovisioning behavior says. See SCIM › Scope.
  • OpenID Connect applications with back-channel logout are told to sign the person out. SAML applications and applications with front-channel logout only are not told, and keep their own session until it expires. See About sessions and sign-out.

If you suspended the wrong person, call POST $API/users/{id}/restore, which answers 204. Their revoked reset links, Admin API grants and delegations do not come back.

Remove the account

Remove an account when the person will not come back, for example after a retention period:

curl -X DELETE "$API/users/Jt4mQ8bXz2PwRk6NcY3hVa" -H "$AUTH"

Sovrain answers 204. The account disappears from every list and cannot be brought back, through the API or the admin pages; its data stays in the organization. A second call answers 404, so treat 404 as done. Removing has the same effects as suspending; see Users › Remove a user.

If you want to take away only part of someone’s access

To keep the account but stop access to one application, take the person out of the group that gives access to it:

curl -X DELETE "$API/groups/v6BQgJN59SryMvGUwk7jUP/members/Jt4mQ8bXz2PwRk6NcY3hVa" -H "$AUTH"

Sovrain answers 204, also when the person was not a member. Which groups give access to an application is in the access list of GET $API/apps/{slug} (scope apps:read).

To take the person out of every group at once, send an empty list (scope users:write); they stay in All:

curl -X PUT "$API/users/Jt4mQ8bXz2PwRk6NcY3hVa/groups" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"groups":[]}'

All cannot be left, so an application that gives access to All stays open to the person while the account is active. Leaving both Owners and Admins ends the person’s admin access and their Admin API grants.