Create and send an invitation to join a merchant

curl -X POST https://api-sandbox.koywe.com/api/v1/users/organizations/organizationId/merchants/merchantId/invitations \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "email": "invited.user@example.com",
  "roles": [
    "MERCHANT_ADMIN",
    "MERCHANT_VIEWER"
  ]
}'

{
  "id": "inv_xxxxxxxxxxxxxx",
  "email": "user@example.com",
  "roles": [
    "ADMIN_ROLE",
    "VIEWER_ROLE"
  ],
  "status": "PENDING",
  "expiresAt": "2024-08-15T10:00:00Z",
  "createdAt": "2024-08-08T10:00:00Z",
  "invitedByUserId": "k3u_yyyyyyyyyyyyyy",
  "merchantId": "mrc_zzzzzzzzzzzzzz",
  "userExists": true,
  "acceptedAt": "2024-08-09T10:00:00Z",
  "acceptedByUserId": "k3u_xxxxxxxxxxxxxx",
  "rolesAssignedImmediately": true,
  "message": "Invitation sent to user@example.com"
}

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

organizationIdstringRequired

Organization ID

merchantIdstringRequired

Merchant ID to invite the user to

Request

This endpoint expects an object.

emailstringRequired

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

roleslist of stringsRequired

Array of role IDs or names to assign to the user for the merchant. Must contain at least 1 role.

Response

Invitation created and sent successfully.

idstring

Invitation ID

emailstring

Email of the invited user

roleslist of strings

Roles assigned in the invitation

statusenum

Current status of the invitation

Allowed values:

expiresAtdatetime

Expiration date of the invitation token

createdAtdatetime

Creation date of the invitation

invitedByUserIdstring

ID of the user who sent the invitation

merchantIdstring

ID of the merchant for this invitation

userExistsboolean

Indicates whether the invited user already exists in the system

acceptedAtdatetime

Date when the invitation was accepted

acceptedByUserIdstring

ID of the user who accepted the invitation

rolesAssignedImmediatelyboolean

Indicates whether roles were assigned immediately without requiring invitation redemption

messagestring

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

Errors

400

Create Invitation Request Bad Request Error

401

Create Invitation Request Unauthorized Error

403

Create Invitation Request Forbidden Error

409

Create Invitation Request Conflict Error

422

Create Invitation Request Unprocessable Entity Error

500

Create Invitation Request Internal Server Error