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:readandusers:write. Addusers:deleteonly if the script removes accounts, andgroups:writeonly 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
Find the person and note their
id:curl -G "$API/users" -H "$AUTH" --data-urlencode "q=anna@acme.example"qmatches part of the login, the email or the name, so the answer can list more than one person. Take the item whoseloginoremailis exactly the one you looked for. If no item matches, the person is not in the organization; removed people are never listed.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
422withYou 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.Check the result:
curl "$API/users/Jt4mQ8bXz2PwRk6NcY3hVa" -H "$AUTH"The answer has
"status": "suspended". To list everyone who is suspended, callGET $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.
Related
- Automate onboarding with the Admin API.
- Suspend or remove someone, for the same tasks in the admin pages.
- Every endpoint, field and error: Users and Groups.