Create User
Register a new user in a project using either email/password (Fully Managed) or external user ID (BYOU).
Endpoint
/api/v1/projects/{project_id}/usersMethod
POST
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | Unique ID of the project |
Headers
| Header | Required | Description |
|---|---|---|
Content-Type | Yes | application/json |
Authorization | Yes | Bearer access token: Bearer <access_token> |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
display_name | string | Yes | User display name (max 50 chars) |
avatar_url | string | No | URL to avatar image |
external_user_id | string | Conditional | Required if email is not provided (max 100 chars) |
email | string | Conditional | Optional if external_user_id is provided (max 100 chars) |
password | string | Conditional | Required if email is provided (min 8 chars) |
role_id | string | No | Role ID to assign to the user |
Required Permission
users:create
Examples
curl --request POST \
--url https://auth.roled.io/api/v1/projects/2JUSLUee46xG6iEwG8JwPc/users \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...' \
--header 'Content-Type: application/json' \
--data '{
"display_name": "Alice Smith",
"avatar_url": "https://example.com/profiles/alice-smith.jpg",
"external_user_id": "921f28239dcd",
"email": "alice.smith@example.com",
"password": "SecurePassword123!",
"role_id": "2JRtjyxfZudzaJkFczgoUY"
}'Error Codes
| Code | HTTP Status | Description |
|---|---|---|
invalid_params | 400 | Invalid or missing request parameters, headers, or body. |
invalid_authorization_token | 401 | Unauthorized request. The authorization token is missing or invalid. |
insufficient_permission | 403 | Insufficient permissions to access this resource. |
project_not_found | 404 | The requested project could not be found. |
role_not_found | 404 | The requested role could not be found. |
user_external_id_already_used | 409 | A user with this external ID already exists in the project. |
user_email_already_used | 409 | A user with this email address already exists. |
system_error | 500 | An unexpected error occurred. Please try again later. |