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

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:read and users:write, plus apps:write for step 5. apps:write also 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

  1. 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.

  2. 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 from a-z 0-9 . _ - and gets an invitation link instead. Entries carry no names. Sending groups needs the groups:write scope.

  3. 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_url to the person yourself. It is returned only this once
    skippedNot invited, for example an invalid entry or an existing member; see reason
    failedNot invited; see reason

    emailed is reported even when sending the email failed. If someone says the email never arrived, send it again with POST $API/users/{id}/invite, which answers {"status":"sent"}, "failed" or "suppressed". Invitations are valid for 7 days.

  4. 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 …/attributes replaces the whole set, so send every attribute the person should keep. A key that is not one of the organization’s attributes is refused with 422.

  5. 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 204 and is safe to repeat.

  6. 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.