API Reference

Create a User

POST/v1/users

Create a user.

USER_CREATE_START
USER_CREATE_SUCCESS
USER_CREATE_FAIL

Roles

adminissuermanaged-issuer

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

Create a User

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

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"  },  "authenticationProvider": {    "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",    "url": "https://example-university.au.auth0.com",    "subjectId": "example-university-oauth2|123456789"  }}

Retrieve all Users

GET/v1/users

Returns a list of all users on your tenant.

Roles

adminissuermanaged-issuer

Analytics Events

USER_RETRIEVE_LIST_STARTUSER_RETRIEVE_LIST_SUCCESSUSER_RETRIEVE_LIST_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Range size of returned list.

Range1 <= value <= 1000

Default100

cursor?string

Starting point for the list of entries.

Response Body

`application/json`

curl -X GET "https://example.com/v1/users"

{  "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",  "data": [    {      "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba",      "claims": {        "externalUserId": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba"      },      "authenticationProvider": {        "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",        "url": "https://example-university.au.auth0.com",        "subjectId": "example-university-oauth2|123456789"      }    }  ]}

Retrieve a User

GET/v1/users/{id}

Retrieve an existing user by providing its ID.

USER_RETRIEVE_START
USER_RETRIEVE_SUCCESS
USER_RETRIEVE_FAIL

Roles

adminissuermanaged-issuer

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

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"  },  "authenticationProvider": {    "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",    "url": "https://example-university.au.auth0.com",    "subjectId": "example-university-oauth2|123456789"  }}

Update a User

PUT/v1/users/{id}

Updates an existing user by providing its ID.

USER_UPDATE_START
USER_UPDATE_SUCCESS
USER_UPDATE_FAIL

Roles

adminissuermanaged-issuer

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

Update a User

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

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"  },  "authenticationProvider": {    "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",    "url": "https://example-university.au.auth0.com",    "subjectId": "example-university-oauth2|123456789"  }}

Delete a User

DELETE/v1/users/{id}

Deletes a user and removes all data related to them by providing the user ID.

Roles

adminissuermanaged-issuer

Analytics Events

USER_DELETE_STARTUSER_DELETE_SUCCESSUSER_DELETE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Search Users

POST/v1/users/search

Returns a list of users from the tenant that match all the provided search criteria (all criteria are optional).

Roles

adminissuermanaged-issuer

Analytics Events

USER_SEARCH_STARTUSER_SEARCH_SUCCESSUSER_SEARCH_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

The search criteria

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

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"      },      "authenticationProvider": {        "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",        "url": "https://example-university.au.auth0.com",        "subjectId": "example-university-oauth2|123456789"      }    }  ]}

Retrieve User credentials Data

GET/v1/users/{userId}/credentials

Returns metadata for all the credentials issued to the provided userId.

Roles

adminissuermanaged-issuer

Analytics Events

USER_CREDENTIAL_RETRIEVE_LIST_STARTUSER_CREDENTIAL_RETRIEVE_LIST_SUCCESSUSER_CREDENTIAL_RETRIEVE_LIST_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Range size of returned list.

Range1 <= value <= 1000

Default100

cursor?string

Starting point for the list of entries.

Response Body

`application/json`

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"}

Create a User

POST/v1/users

Create a user.

USER_CREATE_START
USER_CREATE_SUCCESS
USER_CREATE_FAIL

Roles

adminissuermanaged-issuer

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

Create a User

TypeScript Definitions

Use the request body type in TypeScript.

claims?

User claims to be persisted. No claims are persisted by default. Consider PII implications before persisting any claims.

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.

Response Body

`application/json`

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"  },  "authenticationProvider": {    "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",    "url": "https://example-university.au.auth0.com",    "subjectId": "example-university-oauth2|123456789"  }}

Retrieve all Users

GET/v1/users

Returns a list of all users on your tenant.

Roles

adminissuermanaged-issuer

Analytics Events

USER_RETRIEVE_LIST_STARTUSER_RETRIEVE_LIST_SUCCESSUSER_RETRIEVE_LIST_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Range size of returned list.

Range1 <= value <= 1000

Default100

cursor?string

Starting point for the list of entries.

Response Body

`application/json`

curl -X GET "https://example.com/v1/users"

{  "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",  "data": [    {      "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba",      "claims": {        "externalUserId": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba"      },      "authenticationProvider": {        "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",        "url": "https://example-university.au.auth0.com",        "subjectId": "example-university-oauth2|123456789"      }    }  ]}

Retrieve a User

GET/v1/users/{id}

Retrieve an existing user by providing its ID.

USER_RETRIEVE_START
USER_RETRIEVE_SUCCESS
USER_RETRIEVE_FAIL

Roles

adminissuermanaged-issuer

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

User ID

Formatuuid

Response Body

`application/json`

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"  },  "authenticationProvider": {    "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",    "url": "https://example-university.au.auth0.com",    "subjectId": "example-university-oauth2|123456789"  }}

Update a User

PUT/v1/users/{id}

Updates an existing user by providing its ID.

USER_UPDATE_START
USER_UPDATE_SUCCESS
USER_UPDATE_FAIL

Roles

adminissuermanaged-issuer

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

User ID

Formatuuid

Request Body

application/json

Update a User

TypeScript Definitions

Use the request body type in TypeScript.

claims?

User claims to be persisted. No claims are persisted by default. Consider PII implications before persisting any claims.

authenticationProvider?

Response Body

`application/json`

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"  },  "authenticationProvider": {    "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",    "url": "https://example-university.au.auth0.com",    "subjectId": "example-university-oauth2|123456789"  }}

Delete a User

DELETE/v1/users/{id}

Deletes a user and removes all data related to them by providing the user ID.

Roles

adminissuermanaged-issuer

Analytics Events

USER_DELETE_STARTUSER_DELETE_SUCCESSUSER_DELETE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

User ID

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/users/8241400f-de3b-42c5-ad7c-8a380039e796"

Empty

Search Users

POST/v1/users/search

Returns a list of users from the tenant that match all the provided search criteria (all criteria are optional).

Roles

adminissuermanaged-issuer

Analytics Events

USER_SEARCH_STARTUSER_SEARCH_SUCCESSUSER_SEARCH_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

The search criteria

TypeScript Definitions

Use the request body type in TypeScript.

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?number

Range size of returned entries, default 100

Range1 <= value <= 1000

cursor?string

Starting point for the range of entries

Response Body

`application/json`

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"      },      "authenticationProvider": {        "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",        "url": "https://example-university.au.auth0.com",        "subjectId": "example-university-oauth2|123456789"      }    }  ]}

Retrieve User credentials Data

GET/v1/users/{userId}/credentials

Returns metadata for all the credentials issued to the provided userId.

Roles

adminissuermanaged-issuer

Analytics Events

USER_CREDENTIAL_RETRIEVE_LIST_STARTUSER_CREDENTIAL_RETRIEVE_LIST_SUCCESSUSER_CREDENTIAL_RETRIEVE_LIST_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

userId*string

User ID

Formatuuid

Query Parameters

limit?number

Range size of returned list.

Range1 <= value <= 1000

Default100

cursor?string

Starting point for the list of entries.

Response Body

`application/json`

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"}

Roles

201application/json

400application/json

Roles

Analytics Events

200application/json

400application/json

Roles

200application/json

400application/json

404application/json

Roles

200application/json

400application/json

404application/json

Roles

Analytics Events

204

400application/json

404application/json

Roles

Analytics Events

200application/json

400application/json

Roles

Analytics Events

200application/json

400application/json

On this page

API Reference

Roles

201application/json

400application/json

Roles

Analytics Events

200application/json

400application/json

Roles

200application/json

400application/json

404application/json

Roles

200application/json

400application/json

404application/json

Roles

Analytics Events

204

400application/json

404application/json

Roles

Analytics Events

200application/json

400application/json

Roles

Analytics Events

200application/json

400application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`