Create Invitation

POST /invitations

Interactive request editor loads with JavaScript.

Authorization

BearerAdminToken

AuthorizationBearer <token>

Organization-scoped admin token. Read operations require a valid token, and write operations require a token with write permission.

In: header

Request Body

application/json

email*string

Address to invite. Lowercased before storage, and the only address that can redeem the resulting link.

Formatemail

role*string

Organization role to grant. A built-in role (owner, admin, member) or an existing custom role name. You cannot grant a role above your own.

expires_in_days?integer

Days until the link stops working. Omit for the deployment default.

Range1 <= value

Response Body

`application/json`

curl -X POST "$AISIX_CP/invitations" \  -H "Authorization: Bearer $AISIX_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "email": "user@example.com",    "role": "string"  }'

Created

{
  "invitation": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
    "email": "string",
    "role": "string",
    "status": "pending",
    "expires_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "inviter": {
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "email": "string",
      "display_name": "string"
    }
  },
  "plaintext": "string",
  "invite_url": "string"
}

Request body or parameters failed validation.

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Missing or invalid bearer.

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "no org context"
  }
}

Authenticated request is not permitted.

{
  "error": {
    "code": "CUSTOM_KEY_DISABLED",
    "message": "custom API key values are disabled for this organization"
  }
}

The address already belongs to a member (`ALREADY_MEMBER`) or already has a pending invitation (`ALREADY_INVITED`).

{
  "error": {
    "code": "ALREADY_MEMBER",
    "message": "this email already belongs to a member of this organization — change their role from the members list instead"
  }
}

Complete operation details and schema variants

POST /invitations

Create Invitation

Invite an email address to join the organization with a given role.

The response carries the invitation token in clear text, once. plaintext and the invite_url built from it are never recoverable afterwards — anyone holding either can redeem the invitation, so deliver it over a channel you trust and treat it like a credential.

Granting a role you do not hold is refused: only an owner may invite an owner, and admin or custom roles require at least admin. Inviting an address that already belongs to a member is refused too — change that member's role instead.

Parameters

Request body

Content type: application/json

email (string, required): Address to invite. Lowercased before storage, and the only address that can redeem the resulting link.
role (string, required): Organization role to grant. A built-in role (owner, admin, member) or an existing custom role name. You cannot grant a role above your own.
expires_in_days (integer, optional): Days until the link stops working. Omit for the deployment default.

Responses

201: Created
invitation (object, required):
invitation.id (string, required):
invitation.org_id (string, required):
invitation.email (string, required): Address the invitation was issued to, lowercased. Redemption is bound to it — no other address can claim the link.
invitation.role (string, required): Organization role the invitee receives on redemption. A built-in role (owner, admin, member) or a custom role name.
invitation.status (string, required): pending is the only redeemable state. expired is derived from expires_at at read time, not stored.
invitation.expires_at (string, required): When the link stops working. null for an invitation with no expiry.
invitation.created_at (string, required):
invitation.inviter (object, required):
invitation.inviter.user_id (string, required):
invitation.inviter.email (string, required):
invitation.inviter.display_name (string, required):
plaintext (string, required): The invitation token, in clear text, returned once.
invite_url (string, required): Redemption link built from the token.
400: Request body or parameters failed validation.
error (object, required): Error details.
error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.
error.message (string, required): Human-readable explanation; safe to surface to operators.
401: Missing or invalid bearer. Response fields (application/json): identical to POST /invitations, response 400 above.
403: Authenticated request is not permitted. Response fields (application/json): identical to POST /invitations, response 400 above.
409: The address already belongs to a member (ALREADY_MEMBER) or already has a pending invitation (ALREADY_INVITED).

Response fields (application/json): identical to POST /invitations, response 400 above.

cURL

curl -X POST '$AISIX_CP/invitations' -H 'Authorization: Bearer $AISIX_TOKEN'

Create Invitation

201application/json

400application/json

401application/json

403application/json

409application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`