Recomly APIEndpointsUsers
Create user
Invite a new member to the organization.
POST /api/app/users
Creates a new user account and adds them to the organization. Optionally sends a Cognito invitation email with a temporary password so the user can set their own credentials. Requires the admin role.
If the organization has a user quota configured (enabledFeatures.users), this endpoint returns 403 when the quota is reached.
Request
See API Basics for required headers.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address for the new user. Must be globally unique across the platform. |
firstName | string | Yes | User's first name. |
lastName | string | Yes | User's last name. |
roles | string[] | No | Array of tenant roles. Allowed values: "admin", "user". Defaults to ["user"]. |
allowPasswordAuth | boolean | No | Whether the user may authenticate with email and password. Defaults to true. Set to false for SSO-only users — requires at least one enabled SSO provider. |
sendInvitation | boolean | No | Whether to send a Cognito invitation email. Defaults to true. Automatically suppressed when allowPasswordAuth is false. |
Sample request
curl -X POST https://api.recomly.com/api/app/users \
-H "Authorization: Bearer rk_live_abc123:def456" \
-H "Content-Type: application/json" \
-d '{
"email": "carol@acmeplumbing.com",
"firstName": "Carol",
"lastName": "Kim",
"roles": ["user"],
"sendInvitation": true
}'Sample response
Status: 201 Created
{
"user": {
"email": "carol@acmeplumbing.com",
"roles": ["user"],
"allowPasswordAuth": true,
"createdAt": "2026-04-15T12:00:00.000Z"
}
}Error responses
See API Basics for standard status codes and error response format.
| Status | Meaning |
|---|---|
400 | Validation failure or SSO provider not configured for allowPasswordAuth: false. |
403 | Caller does not have the admin role, or the organization's user quota is reached. |
409 | Email is already a member of this organization, or already registered on the platform. |