API Conventions

The conventions on this page apply to every endpoint of the ErtisAuth API.

Base URL and routes#

All examples in this documentation use https://auth.example.com as the base URL. ErtisAuth serves its routes from the root of the host; if you publish it under a path prefix (for example /api/v1 behind a gateway), add that prefix to every route.

Routes fall into three groups:

Membership isolation#

A request to a membership-bounded route must be made with a token of that same membership. A valid token of another membership is rejected with 403 AccessDenied, whatever its permissions are.

Headers#

Request and response bodies#

• Bodies are JSON. Field names are snake_case for most resources (email_address, expires_in); providers, mail hooks and the flags of user types use camelCase (defaultRole, mailSubject, isAbstract). Each reference page shows the exact names.
• Dates are ISO 8601 strings in UTC.
• Responses are compressed with Brotli or Gzip when the client accepts it.

Status codes#

Errors#

Errors have a common shape:

{
	"message": "User not found in db by given _id: <66f1c0d2a4b5c6d7e8f90124>",
	"errorCode": "UserNotFound",
	"statusCode": 404
}

Use errorCode in your code; message is meant for people and may change. All codes are listed in Error Codes.

Validation errors carry the list of problems in data:

{
	"message": "Some fields are not validated, invalid or missing. Check response detail.",
	"errorCode": "ModelValidationError",
	"statusCode": 400,
	"data": [ "Expires-in is required", "Secret key is required" ]
}

Errors of a user's custom fields, validated by the user type schema, name the field:

{
	"message": "String length can not be greater than 20",
	"fieldName": "phone",
	"fieldPath": "phone",
	"errorCode": "FieldValidationException",
	"statusCode": 400
}

When several fields are invalid at once, all of them are reported:

{
	"message": "…",
	"errorCode": "ValidationException",
	"statusCode": 400,
	"errors": [
		{ "message": "phone is required", "fieldName": "phone", "fieldPath": "phone" },
		{ "message": "String length can not be less than 2", "fieldName": "firstname", "fieldPath": "firstname" }
	]
}

An id that is not a valid ObjectId answers 400 ParameterFormatError.

Listing resources#

List endpoints (GET /memberships/{membershipId}/users and the like) are paginated and sortable with query parameters:

curl 'https://auth.example.com/memberships/<membership_id>/users?skip=0&limit=2&with_count=true&sort=sys.created_at%20desc' \
	-H 'Authorization: Bearer <access_token>'

{
	"count": 1250,
	"items": [
		{ "_id": "…", "username": "jane", "…": "…" },
		{ "_id": "…", "username": "john", "…": "…" }
	]
}

Without with_count=true, count is not computed.

Querying resources#

Most resources have a POST …/_query endpoint that takes a MongoDB query in where, and an optional projection in select:

curl -X POST 'https://auth.example.com/memberships/<membership_id>/users/_query?limit=50&sort=lastname' \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"where": {
			"user_type": "customer",
			"is_active": true,
			"sys.created_at": { "$gte": "2026-01-01T00:00:00Z" }
		},
		"select": {
			"username": 1,
			"email_address": 1,
			"firstname": 1
		}
	}'

• The pagination and sorting parameters of the list endpoints apply.
• select includes fields with 1 or true and excludes them with 0 or false.
• The membership filter is always added by the server: a query can never read another membership's data.
• JavaScript operators ($where, $function, $accumulator) are rejected with 400 InvalidQuery.
• Hidden fields, such as password_hash, can be neither returned nor used in filters or sorting.
• For users, the optional locale query parameter (e.g. locale=tr) sets the collation of the sorting, so that names sort correctly in that language.

Aggregation#

Active tokens also support POST …/active-tokens/_aggregate, which takes a JSON array of aggregation pipeline stages. The membership filter is added as the first stage by the server.

Only stages that transform the documents flowing through the pipeline are allowed: $match, $project, $addFields, $set, $unset, $group, $sort, $limit, $skip, $count, $unwind, $bucket, $bucketAuto, $sortByCount, $replaceRoot, $replaceWith, $sample, $setWindowFields and $facet. Any other stage, in particular those that read or write other collections ($lookup, $graphLookup, $unionWith, $out, $merge), is rejected with 400 UnsupportedAggregationStage.

curl -X POST 'https://auth.example.com/memberships/<membership_id>/active-tokens/_aggregate' \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '[
		{ "$group": { "_id": "$user_id", "sessions": { "$sum": 1 } } },
		{ "$sort": { "sessions": -1 } },
		{ "$limit": 10 }
	]'

Searching resources#

Users, roles, applications and memberships have a full-text search:

curl 'https://auth.example.com/memberships/<membership_id>/users/search?keyword=lovelace&limit=10' \
	-H 'Authorization: Bearer <access_token>'

keyword is required (400 SearchKeywordRequired otherwise). Pagination and sorting work as in the list endpoints.

Creating and updating#

• POST creates a resource and answers 201 Created with the resource and a Location header.
• PUT /{id} updates a resource. The id always comes from the route; an _id in the body is ignored.
• An update that changes nothing answers 409 IdenticalDocumentError. Treat it as a success if your client may send unchanged data.
• A sys object sent in a body is ignored.

Bulk delete#

Users, roles, applications, webhooks, mail hooks and code policies can be deleted in bulk with DELETE on the collection route and a JSON array of ids as the body:

curl -X DELETE 'https://auth.example.com/memberships/<membership_id>/users' \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '[ "66f1c0d2a4b5c6d7e8f90124", "66f1c0d2a4b5c6d7e8f90127" ]'