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.
| Field | Type | Required | Notes |
|---|---|---|---|
entries | array of strings | no | Email addresses and login names. Each string is also split at commas and line breaks. |
groups | array of group ids | no | Groups every invited person joins, besides All and the default groups |
How an entry is read:
| Entry | Becomes | Rules |
|---|---|---|
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."
}
]
}
| Field | Notes |
|---|---|
entry | The entry as read |
outcome | emailed, created, skipped or failed |
user | Id of the new user, for emailed and created |
invite_url | For created only. The one-time link to hand to the person. It is returned only in this response. |
reason | For skipped and failed |
| Outcome | Meaning |
|---|---|
emailed | The user was created and the invitation email was attempted. emailed is returned even when sending failed; the result of the send is not reported. |
created | A login-only user was created. Hand over invite_url. |
skipped | The entry is invalid or the person is already a member |
failed | The user could not be created, for example Already a member (created meanwhile). |
Invited users:
- have the status
inviteduntil they open the link and choose a password; - join
All, every default group and the groups ingroups; - 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:
| Status | error | When |
|---|---|---|
| 403 | insufficient_scope | groups is not empty and the token lacks groups:write |
| 422 | refused | More 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 |
| 429 | rate_limited | The emails of this request would go over 200 invitation emails per hour per admin. Nothing is sent. |