API Reference
Create a User
Create a user.
- USER_CREATE_START
- USER_CREATE_SUCCESS
- USER_CREATE_FAIL
Roles
bearerAuthAuthorizationBearer <token>Create a User
application/json- body
claims?User claims to be persisted. No claims are persisted by default. Consider PII implications before persisting any claims.
claimSets?User claims to be persisted per claim set, keyed by credential configuration identifier and then by claim set identifier. No claim sets are persisted by default. Consider PII implications before persisting any claims.
When updating a user, providing this property replaces the user's existing claim sets. Omitting it leaves them unchanged.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
authenticationProvider?Authentication Provider information for the user. This enables linking the user to an external identity provider. If implemented insecurely, this process can be exploited by malicious actors to gain unauthorized access to legitimate user accounts.
To mitigate this risk, require authentication for both accounts involved in the link, whether the link is created manually or automatically. Always prompt the user to enter credentials to verify ownership before establishing the link.
User created
application/json- response
id?stringUser unique identifier.
uuidclaims?User claims.
claimSets?User claims persisted per claim set, keyed by credential configuration identifier and then by claim set identifier. Only present when claim sets are persisted for this user.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
authenticationProvider?Authentication Provider information for the user.
curl -X POST "https://example.com/v1/users" \ -H "Content-Type: application/json" \ -d '{}'{ "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba", "claims": { "externalUserId": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba" }, "claimSets": { "707e920a-f342-443b-ae24-6946b7b5033e": { "claim-set-id-1": { "givenName": "Alice" }, "claim-set-id-2": { "givenName": "Bob" } } }, "authenticationProvider": { "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "url": "https://example-university.au.auth0.com", "subjectId": "example-university-oauth2|123456789" }}Retrieve all Users
Returns a list of all users on your tenant.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>limit?numberRange size of returned list.
1 <= value <= 1000100cursor?stringStarting point for the list of entries.
Users retrieved
application/json- response
nextCursor?stringStarting point for next cursor to use in a page
data?array<>Includes matching user objects.
curl -X GET "https://example.com/v1/users"{ "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM", "data": [ { "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba", "claims": { "externalUserId": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba" }, "claimSets": { "707e920a-f342-443b-ae24-6946b7b5033e": { "claim-set-id-1": { "givenName": "Alice" }, "claim-set-id-2": { "givenName": "Bob" } } }, "authenticationProvider": { "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "url": "https://example-university.au.auth0.com", "subjectId": "example-university-oauth2|123456789" } } ]}Retrieve a User
Retrieve an existing user by providing its ID.
- USER_RETRIEVE_START
- USER_RETRIEVE_SUCCESS
- USER_RETRIEVE_FAIL
Roles
bearerAuthAuthorizationBearer <token>id*stringUser ID
uuidUser retrieved
application/json- response
id?stringUser unique identifier.
uuidclaims?User claims.
claimSets?User claims persisted per claim set, keyed by credential configuration identifier and then by claim set identifier. Only present when claim sets are persisted for this user.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
authenticationProvider?Authentication Provider information for the user.
curl -X GET "https://example.com/v1/users/8241400f-de3b-42c5-ad7c-8a380039e796"{ "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba", "claims": { "externalUserId": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba" }, "claimSets": { "707e920a-f342-443b-ae24-6946b7b5033e": { "claim-set-id-1": { "givenName": "Alice" }, "claim-set-id-2": { "givenName": "Bob" } } }, "authenticationProvider": { "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "url": "https://example-university.au.auth0.com", "subjectId": "example-university-oauth2|123456789" }}Update a User
Updates an existing user by providing its ID.
- USER_UPDATE_START
- USER_UPDATE_SUCCESS
- USER_UPDATE_FAIL
Roles
bearerAuthAuthorizationBearer <token>id*stringUser ID
uuidUpdate a User
application/json- body
claims?User claims to be persisted. No claims are persisted by default. Consider PII implications before persisting any claims.
claimSets?User claims to be persisted per claim set, keyed by credential configuration identifier and then by claim set identifier. No claim sets are persisted by default. Consider PII implications before persisting any claims.
When updating a user, providing this property replaces the user's existing claim sets. Omitting it leaves them unchanged.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
authenticationProvider?Authentication Provider information for the user. This enables linking the user to an external identity provider. If implemented insecurely, this process can be exploited by malicious actors to gain unauthorized access to legitimate user accounts.
To mitigate this risk, require authentication for both accounts involved in the link, whether the link is created manually or automatically. Always prompt the user to enter credentials to verify ownership before establishing the link.
User updated
application/json- response
id?stringUser unique identifier.
uuidclaims?User claims.
claimSets?User claims persisted per claim set, keyed by credential configuration identifier and then by claim set identifier. Only present when claim sets are persisted for this user.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
authenticationProvider?Authentication Provider information for the user.
curl -X PUT "https://example.com/v1/users/8241400f-de3b-42c5-ad7c-8a380039e796" \ -H "Content-Type: application/json" \ -d '{}'{ "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba", "claims": { "externalUserId": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba" }, "claimSets": { "707e920a-f342-443b-ae24-6946b7b5033e": { "claim-set-id-1": { "givenName": "Alice" }, "claim-set-id-2": { "givenName": "Bob" } } }, "authenticationProvider": { "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "url": "https://example-university.au.auth0.com", "subjectId": "example-university-oauth2|123456789" }}Delete a User
Deletes a user and removes all data related to them by providing the user ID.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>id*stringUser ID
uuidUser deleted
curl -X DELETE "https://example.com/v1/users/8241400f-de3b-42c5-ad7c-8a380039e796"Search Users
Returns a list of users from the tenant that match all the provided search criteria (all criteria are optional).
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>The search criteria
application/json- body
claims?Filter users by claims. Nested objects are supported. Text values must be an exact match.
authenticationProvider?Filter users by their unique identifier in the configured Authentication Provider.
limit?numberRange size of returned entries, default 100
1 <= value <= 1000cursor?stringStarting point for the range of entries
Users retrieved
application/json- response
nextCursor?stringStarting point for next cursor to use in a page
data?array<>Includes all matching user objects.
curl -X POST "https://example.com/v1/users/search" \ -H "Content-Type: application/json" \ -d '{}'{ "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM", "data": [ { "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba", "claims": { "externalUserId": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba" }, "claimSets": { "707e920a-f342-443b-ae24-6946b7b5033e": { "claim-set-id-1": { "givenName": "Alice" }, "claim-set-id-2": { "givenName": "Bob" } } }, "authenticationProvider": { "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "url": "https://example-university.au.auth0.com", "subjectId": "example-university-oauth2|123456789" } } ]}Retrieve User credentials Data
Returns metadata for all the credentials issued to the provided userId.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>userId*stringThe user ID represents a unique identifier for a user in the system. The user ID is generated by the system when a user is created, and is returned in the response when retrieving users.
uuidlimit?numberRange size of returned list.
1 <= value <= 1000100cursor?stringStarting point for the list of entries.
User credentials retrieved
application/json- response
data?array<||>- Includes metadata for all credentials referenced by the provided
UserId. - Properties returned depend on the credential type, with the exception of the following properties which are always returned:
idtypeprofilesessionIdcredentialConfigurationId
- Properties are only returned for credentials issued using Platform v11.0.0 or later, with the exception of the following properties which are always returned:
idtypeprofilesessionId
nextCursor?nextCursorStarting point for next cursor to use in a paginated list.
curl -X GET "https://example.com/v1/users/41458e5a-9092-40b7-9a26-d4eb43c5792f/credentials"{ "data": [ { "id": "552b35fe-a3ed-4c33-8c3c-64810c712323", "type": "org.iso.18013.5.1.mDL", "profile": "mobile", "offerId": "b0877ef9-deaf-4c88-8765-2b5aad2913d9", "sessionId": "4da5bce7-39d0-482e-8972-c674c688e01a", "credentialConfigurationId": "3948c40e-6e19-4ffc-933c-91f643f24264", "devicePublicKey": { "kty": "EC", "crv": "P-256", "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo" }, "namespaces": { "org.iso.18013.5.1": { "given_name": { "digestID": 0, "digest": "8GWbUyIRA2xATs5ILEa0fVZF1QQt4JL5gG2aCtVsazU" }, "family_name": { "digestID": 1, "digest": "R4jk/m0wX9KhENp7DVPr9AM7Hz+CJoEJNKJRQo92FCI" } } }, "msoHash": "OsPO++ARsvvJYswmuzN8E3rxN+jAkbWbxhqVIOfM1Go", "issuedDate": "2025-06-28T12:34:56.000Z", "validFrom": "2025-06-30T12:00:00.000Z", "validUntil": "2025-07-30T12:00:00.000Z", "status": "valid" } ], "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"}How would you rate this page?
Last updated on