Users

Users are the people who sign in to your applications. Each user belongs to one membership, has a role and a user type, and may have permissions of their own (see Authorization).

The user object#

{
	"_id": "66f1c0d2a4b5c6d7e8f90127",
	"username": "ada",
	"email_address": "ada@example.com",
	"firstname": "Ada",
	"lastname": "Lovelace",
	"role": "support",
	"user_type": "employee",
	"permissions": [ "orders.approve" ],
	"forbidden": [],
	"is_active": true,
	"source_provider": "ErtisAuth",
	"connected_accounts": [],
	"membership_id": "66f1c0d2a4b5c6d7e8f90123",
	"sys": {
		"created_at": "2026-01-01T12:00:00Z",
		"created_by": "admin",
		"modified_at": "2026-01-05T09:12:44Z",
		"modified_by": "ada"
	},
	"department": "Engineering",
	"phone": "+44 20 7946 0000"
}

The standard fields come from the built-in base-user type; every other field (department, phone above) is declared by the user's user type.

The password hash is stored in a hidden field and is never returned, filtered or sorted on.

Endpoints#

All routes are under /memberships/{membershipId}.

The activation, reset and OTP endpoints are described in Account Recovery and Activation.

A user can always update their own record (the own-record rule), except for the privileged fields.

Get a user#

GET /memberships/{membershipId}/users/{id}
Authorization: Bearer <access_token>

Response 200 OK: the user, with the custom fields of their user type. 404 UserNotFound when it does not exist.

List, query and search users#

GET /memberships/{membershipId}/users?skip=0&limit=20&with_count=true&sort=lastname
POST /memberships/{membershipId}/users/_query
GET /memberships/{membershipId}/users/search?keyword=ada

See API Conventions. The query endpoint also accepts locale (e.g. locale=tr) to sort names by the rules of a language. The search looks for the keyword in username, firstname, lastname and email_address, ignoring case and diacritics.

Find a user by email address:

curl -X POST 'https://auth.example.com/memberships/<membership_id>/users/_query' \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{ "where": { "email_address": "ada@example.com" } }'

Create a user#

curl -X POST https://auth.example.com/memberships/<membership_id>/users \
	-H 'Authorization: Bearer <access_token>' \
	-H 'X-Host: https://app.example.com/activate' \
	-H 'Content-Type: application/json' \
	-d '{
		"username": "ada",
		"email_address": "ada@example.com",
		"firstname": "Ada",
		"lastname": "Lovelace",
		"password": "<at least 6 characters>",
		"role": "support",
		"user_type": "employee",
		"department": "Engineering"
	}'

• The body is validated against the schema of user_type, including its inherited fields. Unknown fields are rejected unless the user type allows additional properties.
• password is required and must be at least 6 characters long. It is hashed with the membership's algorithm and never stored in plain text.
• is_active, source_provider and connected_accounts in the body are ignored: when the membership requires activation, the user is created inactive and the activation mail is sent to the link host in X-Host; otherwise the user is active immediately.
• user_type is required in practice: without it the built-in base-user type would be used, which is abstract (400 InheritedTypeIsAbstract).
• email_address is stored in lower case.

Response 201 Created: the user.

A duplicate username, email address or other unique field is reported as a field error:

{
	"message": "…",
	"errorCode": "ValidationException",
	"statusCode": 400,
	"errors": [
		{
			"message": "The 'email_address' field has unique constraint. The same value is already using in another user.",
			"fieldName": "email_address",
			"fieldPath": "email_address"
		}
	]
}

Update a user#

PUT /memberships/{membershipId}/users/{id}

Updates are partial: the fields you send are merged into the current user, the others keep their values.

curl -X PUT https://auth.example.com/memberships/<membership_id>/users/<user_id> \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{ "lastname": "King", "department": "Research" }'

• The merged user is validated against the schema of its user type.
• The password can't be changed here; use change password.
• Changing role, permissions, forbidden, is_active or user_type requires a real users.update permission on the user, also when users update themselves (see Authorization).
• user_type can't be changed once the user is created: sending another type answers 400 UserTypeImmutable. To move a user to another type, create a new user.

Response 200 OK: the updated user. An update without any change answers 409 IdenticalDocumentError.

Delete a user#

DELETE /memberships/{membershipId}/users/{id}

Response 204 No Content, or 404 UserNotFound. Several users can be deleted at once with bulk delete.

Change a password#

PUT /memberships/{membershipId}/users/{id}/change-password
Content-Type: application/json

{ "password": "<new password>" }

Response 200 OK.

After a password change the user is signed out on every device: all their tokens are revoked. When users change their own password, the session they used to change it stays signed in. This protects the account after a takeover: changing the password also kicks the attacker out.

A user can change their own password with the own-record rule; changing someone else's password requires users.update on them.

Check the caller's password#

Asks whether a password is the caller's own current password, for example before a sensitive operation:

GET /memberships/{membershipId}/users/check-password?password=<password>
Authorization: Bearer <access_token>

Answers 200 OK when it matches and 401 when it does not.

Activate a user#

GET /memberships/{membershipId}/users/{id}/activate

Activates the user without an activation mail, for example by an administrator. Response 200 OK with the user, 400 UserAlreadyActive if already active.

Freeze a user#

GET /memberships/{membershipId}/users/{id}/freeze

Deactivates the user and revokes all their tokens: they are signed out everywhere and can't sign in again until they are activated. Pending activation links stop working too. Response 200 OK with the user, 400 UserAlreadyInactive if already inactive.

Events#

See Events.