Users

Create and send an organization invitation

Create an invitation to join an existing organization. The organization ID is specified in the URL.

post/api/v1/users/organizations/{organizationId}/invitations

Request

  • Base URL: https://api-sandbox.koywe.com
  • URL: https://api-sandbox.koywe.com/api/v1/users/organizations/{organizationId}/invitations
  • Auth: HTTP bearer

Path parameters

organizationIdstring required

Organization ID to invite the user to

Request body

emailstring required

Email address or API username (api_<uuid> format) of the user to invite

rolesstring[] required

Array of role IDs to assign to the user for the organization. Must contain at least 1 role. Available roles: k3r_super_admin, k3r_admin, k3r_treasury_manager, k3r_operator, k3r_viewer

Example request

{
  "email": "invited.user@example.com",
  "roles": [
    "k3r_admin"
  ]
}

Response

Organization invitation created and sent successfully.

successboolean required

Indicates whether the operation was successful

messagestring required

Message describing the invitation result. For immediate assignments: "Roles assigned immediately...". For traditional flow: "Invitation sent to..."

organizationIdstring required

ID of the organization for this invitation

userExistsboolean required

Indicates whether the invited user already exists in the system

rolesAssignedImmediatelyboolean

Indicates whether roles were assigned immediately without requiring invitation redemption

pendingApprovalIdstring

If the invitation requires policy approval (sensitive roles), the pending approval ID. The root passkey holder must approve this before the invitation proceeds.

Example response

{
  "success": true,
  "message": "Invitation sent to user@example.com for organization My Organization",
  "organizationId": "org3_xxxxxxxxxxxxxx",
  "userExists": true,
  "rolesAssignedImmediately": true,
  "pendingApprovalId": "pa_xxxxxxxxxxxxxx"
}

Changes

No recorded changes to this operation across all 1 revision of this API.