Organisations
Invite an address to an organisation
Emails the address a one-time link and records a pending invitation for seven days.
POST
/orgs/{org}/invitesTL;DR
| Question | Answer |
|---|---|
| What does it do? | Invite an address to an organisation. |
| What does it take? | A JSON body of type CreateInviteBody. |
| What does it return? | Status 201 with a body of type OrganisationInvite. |
| What can go wrong? | 400 the body is not valid; 401 not signed in; 403 the caller's role may not invite (orgs.forbidden), the organisation is full (orgs.member_limit_reached), or the request came from an origin that may not make changes; 404 no such organisation, or the caller is not a member of it; 409 the address is already a member (orgs.already_member) or already invited (orgs.already_invited); 429 too many requests; 502 the email could not be sent, and no invitation was kept; 503 organisations are not set up on this server. Every failure uses the one error envelope. |
What it does
Emails the address a one-time link and records a pending invitation for seven days. The person must sign in with that address to accept. The owner invites as admin, member or reader, an admin only as member or reader. 403 orgs.member_limit_reached when members plus pending invitations fill the owner's plan; 502 and no invitation when the email cannot be sent.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
Request body
The body has the type CreateInviteBody.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | yes | The address to invite. The person must sign in with this address to accept. at least 3 characters; at most 254 characters. |
role | "admin" | "member" | "reader" | yes | admin, member or reader. An admin can invite and remove members and readers, rename the organisation and manage its keys; a member can publish and change their own diagrams; a reader can view and download and change nothing. Only the owner offers admin or changes a role. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The invitation. | OrganisationInvite |
| 400 | The body is not valid. | ErrorResponse |
| 401 | Not signed in. | ErrorResponse |
| 403 | The caller's role may not invite (orgs.forbidden), the organisation is full (orgs.member_limit_reached), or the request came from an origin that may not make changes. | ErrorResponse |
| 404 | No such organisation, or the caller is not a member of it. | ErrorResponse |
| 409 | The address is already a member (orgs.already_member) or already invited (orgs.already_invited). | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 502 | The email could not be sent, and no invitation was kept. | ErrorResponse |
| 503 | Organisations are not set up on this server. | ErrorResponse |
Response body
A 201 answer has the type OrganisationInvite.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
email | string | yes | |
role | "admin" | "member" | "reader" | yes | |
createdAt | integer | yes | Milliseconds since the epoch. |
expiresAt | integer | yes | Milliseconds since the epoch. Seven days after it was made. |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |