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

Reference

Invitations

Admin API endpoint for inviting people to the organization by email address or login name.

The endpoint under https://acme.sovrain.net/api/v1/invites. Authentication, conventions and the error format are on Admin API. To resend an invitation, see Users.

Invite people

POST /api/v1/invites

Scope: invites:write. Also groups:write when groups is not empty.

FieldTypeRequiredNotes
entriesarray of stringsnoEmail addresses and login names. Each string is also split at commas and line breaks.
groupsarray of group idsnoGroups every invited person joins, besides All and the default groups

How an entry is read:

EntryBecomesRules
Contains @An invitation by email. The login name is the address as typed.3 to 254 characters. An invitation email is sent.
No @An invitation by login name, without email. A one-time link is returned.3 to 32 characters from a-z 0-9 . _ -, turned to lower case

The API takes plain addresses and login names only. Names (Anna Nowak <anna@acme.example>), CSV and vCard are read by the admin pages, not by the API.

{
  "entries": ["anna@acme.example", "bob", "x", "jane"],
  "groups": ["SuT8oWQLVMPzwYQyhKjm32"]
}

Response 200, one result per entry:

{
  "results": [
    {
      "entry": "anna@acme.example",
      "outcome": "emailed",
      "user": "FomjVqEuLmL5CBPAfVwYK2"
    },
    {
      "entry": "bob",
      "outcome": "created",
      "user": "7u5yQZMoFbZ9C4bnwi3Nph",
      "invite_url": "https://acme.sovrain.net/accept-invite?token=<44-character token>"
    },
    {
      "entry": "x",
      "outcome": "skipped",
      "reason": "Login name must be 3-32 characters: lowercase letters, digits, dot, underscore, or hyphen."
    },
    {
      "entry": "jane",
      "outcome": "skipped",
      "reason": "Already a member."
    }
  ]
}
FieldNotes
entryThe entry as read
outcomeemailed, created, skipped or failed
userId of the new user, for emailed and created
invite_urlFor created only. The one-time link to hand to the person. It is returned only in this response.
reasonFor skipped and failed
OutcomeMeaning
emailedThe user was created and the invitation email was attempted. emailed is returned even when sending failed; the result of the send is not reported.
createdA login-only user was created. Hand over invite_url.
skippedThe entry is invalid or the person is already a member
failedThe user could not be created, for example Already a member (created meanwhile).

Invited users:

  • have the status invited until they open the link and choose a password;
  • join All, every default group and the groups in groups;
  • have an invitation link valid for 7 days. For an email invitation, the link works only while the account still has the address it was sent to.

Errors:

StatuserrorWhen
403insufficient_scopegroups is not empty and the token lacks groups:write
422refusedMore than 100 distinct entries, or an entry over 254 characters: N entries were not added (at most 100 entries of at most 254 characters); nothing was sent.; an unknown group
429rate_limitedThe emails of this request would go over 200 invitation emails per hour per admin. Nothing is sent.