Invite a user to an organization

POST

/organizations/{org_id}/invitations

curl --request POST \
  --url https://api.perstat.io/organizations/example/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "example", "role": "example" }'

• Production

Creates a pending invitation for the given email and role, enforcing role assignment rules and the plan’s seat limit (402 when members plus open invitations exceed it). An invitation email is sent when possible; if delivery is unavailable or fails, the response contains the invite token so the link can be shared manually. Returns 409 if the user is already a member or an invitation already exists, and 422 (disposable_email) for a disposable email address. Invitations are accepted through the web application, not through this API. Accepts API keys with the org:write scope, subject to current role and resource grants.

Authorizations

• bearer

Parameters

Path Parameters

org_id

required

string

Request Body^required

Media typeapplication/json

object

email

required

string

role

required

string

Example^generated

{
  "email": "example",
  "role": "example"
}

Responses

201

Resource created. The response body contains the created resource.

Media typeapplication/json

object

invitation

required

object

email

required

string

expires_at_unix

required

integer format: int64

id

required

Public-ID der Einladung (inv_…).

string

role

required

string

invite_token

Dev-Modus (kein SMTP): das einmalige Einladungs-Token, damit das Frontend den Einladungs-Link selbst anzeigen kann. Mit Mailer wäre dies null und der Link würde per E-Mail zugestellt.

string | null

Example^generated

{
  "invitation": {
    "email": "example",
    "expires_at_unix": 1,
    "id": "example",
    "role": "example"
  },
  "invite_token": "example"
}

400

The request is invalid. Check the supplied fields and values.

401

Authentication is missing or invalid.

403

The authenticated caller does not have permission to perform this operation.

409

Already a member or invite exists

422

Disposable email address (disposable_email)