How-to guide
Automate onboarding with the Admin API
Invite new people, put them in a group, fill in their details and give the group access to an app, from a script.
This guide onboards new people from a script, for example one fed by your HR system: it invites them into a group,
fills in their details and makes sure the group can use an app. 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 the steps below use:
groups:read,groups:write,invites:write,users:readandusers:write, plusapps:writefor step 5.apps:writealso allows replacing an app’s client secret, which breaks the app until it gets the new one, and setting its SCIM token, so leave it out if the group already has access. - If you want to set custom attributes, an admin must first add them to the organization.
In the examples, $TOKEN holds the access token:
API=https://acme.sovrain.net/api/v1
AUTH="Authorization: Bearer $TOKEN"
Onboard the people
Find the group, and note its
id:curl "$API/groups" -H "$AUTH"If it does not exist yet, create it:
curl "$API/groups" -H "$AUTH" -H "Content-Type: application/json" \ -d '{"name":"Engineering","description":"Developers"}'Sovrain does not refuse a duplicate group name politely (the call fails with
500), so always look the group up first.Invite the people straight into the group:
curl "$API/invites" -H "$AUTH" -H "Content-Type: application/json" \ -d '{"entries":["anna@acme.example","bob"],"groups":["v6BQgJN59SryMvGUwk7jUP"]}'An entry with
@is an email address and gets an invitation email. An entry without@is a login name of 3 to 32 characters froma-z 0-9 . _ -and gets an invitation link instead. Entries carry no names. Sendinggroupsneeds thegroups:writescope.Read the result of each entry:
{"results":[ {"entry":"anna@acme.example","outcome":"emailed","user":"Jt4mQ8bXz2PwRk6NcY3hVa"}, {"entry":"bob","outcome":"created","user":"Pq7…","invite_url":"https://acme.sovrain.net/accept-invite?token=…"} ]}outcomeMeaning emailedAccount created and invitation email handed to the mail relay createdAccount created; deliver invite_urlto the person yourself. It is returned only this onceskippedNot invited, for example an invalid entry or an existing member; see reasonfailedNot invited; see reasonemailedis reported even when sending the email failed. If someone says the email never arrived, send it again withPOST $API/users/{id}/invite, which answers{"status":"sent"},"failed"or"suppressed". Invitations are valid for 7 days.Fill in names and attributes for each new person:
curl -X PATCH "$API/users/Jt4mQ8bXz2PwRk6NcY3hVa" -H "$AUTH" -H "Content-Type: application/json" \ -d '{"first_name":"Anna","last_name":"Nowak"}' curl -X PUT "$API/users/Jt4mQ8bXz2PwRk6NcY3hVa/attributes" -H "$AUTH" -H "Content-Type: application/json" \ -d '{"attributes":{"department":"R&D"}}'PUT …/attributesreplaces the whole set, so send every attribute the person should keep. A key that is not one of the organization’s attributes is refused with422.Give the group access to the app, with a role if the app uses one:
curl -X PUT "$API/apps/portal/groups/v6BQgJN59SryMvGUwk7jUP" -H "$AUTH" -H "Content-Type: application/json" \ -d '{"role":"editor"}'Apps are addressed by their slug. The call answers
204and is safe to repeat.Check who has not accepted yet:
curl "$API/users?status=invited" -H "$AUTH"
Stay within the limits
- At most 100 entries of at most 254 characters per invite request. A larger request is refused as a whole.
- At most 200 invitation emails an hour per admin. A request that would go over sends nothing and answers
429. - At most 600 calls a minute per grant; a new access token from the same grant does not reset it.
When a business rule refuses a call, the API answers 422 with {"error":"refused","error_description":"…"}; the
description is the same text the admin pages show.
Related
- Offboard people with the Admin API, to stop access for people who leave.
- Configure apps with the Admin API, to create the app itself from a script.
- Every endpoint, field and error: Admin API, with Users, Invitations, Groups and Applications.