light-mode-image
Learn
Users

API Reference

Create a User

Create a User

Create a user.

  • USER_CREATE_START
  • USER_CREATE_SUCCESS
  • USER_CREATE_FAIL
POST/v1/users

Authorization

AuthorizationBearer <token>

In: header

Request Body

Create a User

claims?object

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

Empty Object

authenticationProvider?object

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.

curl -X POST "https://example.vii.au01.mattr.global/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"
  }
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Retrieve all Users

Retrieve all users

Returns a list of all users on your tenant.

Analytic events

  • USER_RETRIEVE_LIST_START
  • USER_RETRIEVE_LIST_SUCCESS
  • USER_RETRIEVE_LIST_FAIL
GET/v1/users

Authorization

AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Range size of returned list.

Default100
Range1 <= value <= 1000
cursor?string

Starting point for the list of entries.

curl -X GET "https://example.vii.au01.mattr.global/v1/users?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h"
{
  "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"
      }
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Retrieve a User

Retrieve a user

Retrieve an existing user by providing its ID.

  • USER_RETRIEVE_START
  • USER_RETRIEVE_SUCCESS
  • USER_RETRIEVE_FAIL
GET/v1/users/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

User ID

Formatuuid
curl -X GET "https://example.vii.au01.mattr.global/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"
  }
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Update a User

Update a User

Updates an existing user by providing its ID.

  • USER_UPDATE_START
  • USER_UPDATE_SUCCESS
  • USER_UPDATE_FAIL
PUT/v1/users/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

User ID

Formatuuid

Request Body

Update a User

claims?object

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

Empty Object

authenticationProvider?object

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.

curl -X PUT "https://example.vii.au01.mattr.global/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"
  }
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Delete a User

Delete a user

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

Analytic events

  • USER_DELETE_START
  • USER_DELETE_SUCCESS
  • USER_DELETE_FAIL
DELETE/v1/users/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

User ID

Formatuuid
curl -X DELETE "https://example.vii.au01.mattr.global/v1/users/8241400f-de3b-42c5-ad7c-8a380039e796"
Empty
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Search Users

Search users

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

Analytic events

  • USER_SEARCH_START
  • USER_SEARCH_SUCCESS
  • USER_SEARCH_FAIL
POST/v1/users/search

Authorization

AuthorizationBearer <token>

In: header

Request Body

The search criteria

claims?object

Filter users by claims. Nested objects are supported. Text values must be an exact match.

Empty Object

authenticationProvider?object

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

curl -X POST "https://example.vii.au01.mattr.global/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"
      }
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Retrieve User credentials Data

Retrieve all user credentials data

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

Analytic events

  • USER_CREDENTIAL_RETRIEVE_LIST_START
  • USER_CREDENTIAL_RETRIEVE_LIST_SUCCESS
  • USER_CREDENTIAL_RETRIEVE_LIST_FAIL
GET/v1/users/{userId}/credentials

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

userIdstring

User ID

Formatuuid

Query Parameters

limit?number

Range size of returned list.

Default100
Range1 <= value <= 1000
cursor?string

Starting point for the list of entries.

curl -X GET "https://example.vii.au01.mattr.global/v1/users/41458e5a-9092-40b7-9a26-d4eb43c5792f/credentials?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h"
{
  "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"
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

How would you rate this page?

Guide

Previous Page

Overview

Next Page

On this page

Create a UserRetrieve all UsersRetrieve a UserUpdate a UserDelete a UserSearch UsersRetrieve User credentials Data