Users endpoint

Using this endpoint you can retrieve and delete users. Retrieval is done with the GET command and deletion with the DELETE command.

Retrieve a user by userId

HTTP request

GET https://{instance}.mauth.nevis.cloud/api/v1/users/{userId}

Path parameters

Parameter	Type	Required/Optional	Description
`userId`	UUID	required	Unique identifier of the user to retrieve.

Example HTTP request

cURL
Python 3

Get user by userId
# Set $userId
curl "https://$instance.mauth.nevis.cloud/api/v1/users/$userId" \
  -H "Authorization: Bearer $access_key"

Get user by userId
userId = '7e16ba00-92e2-4fcb-b30e-1af8fdc843aa'
resp = requests.get(f'https://{instance}.mauth.nevis.cloud/api/v1/users/{userId}',
                    headers = {'authorization': f'Bearer {access_key}'})
print(resp.json())

HTTP response

When a user is retrieved, not only the user data is included in the HTTP response, but the data of the registered authenticators as well.

Field	Type	Description
`userId`	UUID	Unique identifier of this user.
`username`	string	The internal customer ID or unique identifier to link a user to your internal systems. The value can be `null`.
`status`	enum	The current status of the user, either `new`: The user has no confirmed authenticator yet; or `active`: The user has registered at least one authenticator and is able to log in.
`createdAt`	string	The date when the user was created.
`updatedAt`	string	The date when the user was last updated.
`authenticators`	array	List of the already registered authenticators.
`authenticators.authenticatorId`	UUID	Unique identifier of the authenticator.
`authenticators.name`	string	The name of the authenticator provided by the user.
`authenticators.type`	enum	Defines the mobile platform for mobile app authenticators. The value is `ios` for iOS, and `android` for Android.
`authenticators.authenticatorType`	enum	Determines the type of the authenticator. The value can be `app`or `fido2`.
`authenticators.state`	enum	Indicates the state of the authenticator.
`authenticators.enrolledAt`	string	The date when the authenticator was registered.
`authenticators.updatedAt`	string	The date when the authenticator was last updated.
`authenticators.uaf`	DICT	If present, this field contains data related to the FIDO UAF authenticator. Only applicable if the `authenticatorType` is `app`.
`authenticators.uaf.userAgent`	string	Optional user agent. The client application sends the `userAgent` when a FIDO UAF authenticator is registered or used for authentication.
`authenticators.uaf.deviceRef`	UUID	Unique identifier of the physical device. This value will not change other than in specific scenarios: Can the Device Ref of the authenticator change?
`authenticators.uaf.userDisabledPushNotification`	boolean	Indicates if a user is disabled (`true`) or enabled (`false`) notifications for their application. When disabled, push authentication is not possible.
`authenticators.fido2`	DICT	Contains FIDO2-specific information of the authenticator. Only applicable if the `authenticatorType` is `fido2`.
`authenticators.fido2.userAgent`	string	Optional User-Agent. The client application (a web browser or a native mobile application) sends the `userAgent` when a FIDO2 authenticator is registered or used for authentication.
`authenticators.fido2.rpId`	string	The identifier in FIDO2 integration prerequisites, for which the authenticator is registered.
`authenticators.fido2.aaguid`	string	The Authenticator Attestation Globally Unique Identifier, a unique number that indicates the type (for example, make and model) of the authenticator.
`authenticators.fido2.userVerificationRequirement`	enum	Describes the user verification requirement of the relying party for the operation. The value of the field can be `required`, `preferred`, or `discouraged`. For more information, see User Verification Requirement Enumeration.
`authenticators.fido2.attestationConveyancePreference`	enum	Specifies the preference of the relying party regarding attestation conveyance during credential generation. The value of the field can be `none`, `indirect`, `direct`, or `enterprise`. For more information, see Attestation Conveyance Preference Enumeration.
`authenticators.fido2.residentKeyRequirement`	enum	Describes the requirements of the relying party for client-side discoverable credentials. The value can be `discouraged`, `preferred`, or `required`. For more information, see Resident Key Requirement Enumeration.
`phones`	array	List of successfully registered phone numbers.
`phones.authenticatorId`	UUID	Unique identifier of the authenticator.
`phones.name`	string	The name of the phone provided by the user.
`phones.authenticatorType`	enum	Determines the type of the authenticator. The value is `sms`.
`phones.state`	enum	Indicates the state of the phone authenticator.
`phones.enrolledAt`	string	The date when the phone was registered.
`phones.updatedAt`	string	The date when the phone was last updated.
`phones.phoneNumber`	string	The actual registered phone number, masked to avoid personally identifiable information.
`recoveryCodes`	DICT	Contains information about the registered recovery codes.
`recoveryCodes.validFrom`	string	The date from which the recovery codes are valid.
`recoveryCodes.validTo`	string	The date until the recovery codes are valid.
`recoveryCodes.state`	enum	Indicates the state of the recovery codes. The value can be `initial` when none of the registered recovery codes have been used, or `active` when at least one transaction was authenticated with a recovery code.
`recoveryCodes.codes`	array	List of the 16 registered recovery codes.
`recoveryCodes.codes.index`	number	Provides an index for the list of recovery codes. The value ranges from `0` to `15`.
`recoveryCodes.codes.usedAt`	string	The date when the recovery code was used for authentication. The value of the field for unused recovery codes is `null`.
`exceededRateLimits`	DICT	Indicates that the push rate limit is reached for the given user. This means that the user and all of their authenticators are blocked. This field and the objects it contains are only present if push rate limiting is enabled for your instance, and the given user reached the set limit.
`exceededRateLimits.push`	DICT	Contains data of the push rate limit.
`exceededRateLimits.push.resetInSeconds`	string	Indicates the remaining amount of time before the rate limit resets and the user gets unblocked. The measurement unit is in UTC epoch seconds.
`exceededRateLimits.push.sent`	string	The number of push notifications sent in set `timeframe`.
`exceededRateLimits.push.timeframe`	ISO 8601 duration	The time frame in which the number of `sent` push notification are counted. The time frame is relative to the current time.

Example HTTP response

User with single authenticator
User with multiple authenticators
User with no authenticators
User is blocked
User not found

200 OK: User is found.

JSON code sample of a user with a single authenticator
{
  "userId": "6a372961-8f09-4804-bf3e-d76cb50777ba",
  "username": "009d56ad-9c28-466d-a407-ba5fce45c6bd",
  "status": "active",
  "createdAt": "2022-05-31T07:55:25Z",
  "updatedAt": "2022-05-31T07:55:25Z",
  "authenticators": [
      {
        "authenticatorId": "007d91e4-8b88-45a0-88ea-672efd4f10ea",
        "name": "iPhone 12 25.07.2023 10:58:02",
        "type": "ios",
        "authenticatorType": "app",
        "state": "active",
        "enrolledAt": "2023-07-25T08:58:07Z",
        "updatedAt": "2023-08-29T17:42:01Z",
        "uaf": {
          "userAgent": "NMASDK/3.3.2.447 (iPhone13,2; iPhoneOS 16.6) ch.nevis.accessapp.muvonda/2.7.20812.812",
          "deviceRef": "be4b7fe8-1785-4818-9550-bb8cd7153fff",
          "userDisabledPushNotification": false
        }
      }
  ],
  "phones": [],
  "recoveryCodes": null
}

200 OK: User is found.

JSON code sample of a user with multiple authenticators
{
  "userId": "4c0e3f90-4ef2-47d3-8355-2496b3bf361c",
  "username": "user123",
  "status": "active",
  "createdAt": "2022-10-15T15:22:12Z",
  "updatedAt": "2022-10-15T15:22:12Z",
  "authenticators": [
      {
          "authenticatorId": "aa5fe8af-40ca-4e7c-b72e-af767bdde974",
          "name": "samsung XY-Z123A Jul 17, 2023 08:59:40",
          "type": "android",
          "authenticatorType": "app",
          "state": "active",
          "enrolledAt": "2023-07-17T06:59:44Z",
          "updatedAt": "2023-07-17T06:59:44Z",
          "uaf": {
            "userAgent": "NMASDK/3.3.0.1443 (samsung SM-G973F; Android 12) ch.nevis.accessapp.muvonda/2.7.0.1878",
            "deviceRef": "be4b7fe8-1785-4818-9550-bb8cd7153fff",
            "userDisabledPushNotification": true
          }
      },
      {
          "authenticatorId": "e312772c-c9d0-4746-aa10-5dba62ae7da0",
          "name": "fido2 auth",
          "authenticatorType": "fido2",
          "state": "unknown",
          "enrolledAt": "2023-02-27T14:46:54Z",
          "updatedAt": "2023-07-11T14:14:31Z",
          "fido2": {
              "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36",
              "rpId": "my-instance-a12345.mauth.nevis.cloud",
              "aaguid": "00000000-0000-0000-0000-000000000000",
              "userVerificationRequirement": "preferred",
              "attestationConveyancePreference": "none",
              "residentKeyRequirement": "discouraged"
          }
      }
  ],
  "phones": [
      {
          "authenticatorId": "3538af23-3132-47b1-b2b4-f95d4f9917d8",
          "name": "+363***12",
          "authenticatorType": "sms",
          "state": "active",
          "enrolledAt": "2023-01-13T14:14:47Z",
          "updatedAt": "2023-01-13T14:15:02Z",
          "phoneNumber": "+363***12"
      }
  ],
  "recoveryCodes": {
      "validFrom": "2023-01-23T18:02:32Z",
      "validTo": "2033-01-20T18:02:32Z",
      "state": "active",
      "codes": [
          {
              "index": 0,
              "usedAt": null
          },
          {
              "index": 1,
              "usedAt": "2023-01-23T18:02:42Z"
          },
          {
              "index": 2,
              "usedAt": null
          },
          {
              "index": 3,
              "usedAt": null
          },
          {
              "index": 4,
              "usedAt": null
          },
          {
              "index": 5,
              "usedAt": null
          },
          {
              "index": 6,
              "usedAt": null
          },
          {
              "index": 7,
              "usedAt": null
          },
          {
              "index": 8,
              "usedAt": null
          },
          {
              "index": 9,
              "usedAt": null
          },
          {
              "index": 10,
              "usedAt": null
          },
          {
              "index": 11,
              "usedAt": null
          },
          {
              "index": 12,
              "usedAt": null
          },
          {
              "index": 13,
              "usedAt": null
          },
          {
              "index": 14,
              "usedAt": null
          },
          {
              "index": 15,
              "usedAt": null
          }
      ]
  }
}

200 OK: User is found.

JSON code sample of a user with no authenticators
{
  "userId": "1aa9dd1c-1330-4c9e-a37b-4004d1c99baa",
  "username": "00cd4d81-5e3d-4ac1-ae53-9a26a3a81358",
  "status": "new",
  "createdAt": "2021-10-27T21:32:34Z",
  "updatedAt": "2021-10-27T21:32:34Z",
  "authenticators": [],
  "phones": [],
  "recoveryCodes": null
}

JSON code sample of a blocked user
{
"userId": "6a372961-8f09-4804-bf3e-d76cb50777ba",
"username": "009d56ad-9c28-466d-a407-ba5fce45c6bd",
"status": "active",
"createdAt": "2022-05-31T07:55:25Z",
"updatedAt": "2022-05-31T07:55:25Z",
"authenticators": [
  {
    "authenticatorId": "007d91e4-8b88-45a0-88ea-672efd4f10ea",
    "name": "iPhone 12 25.07.2023 10:58:02",
    "type": "ios",
    "authenticatorType": "app",
    "state": "active",
    "enrolledAt": "2023-07-25T08:58:07Z",
    "updatedAt": "2023-08-29T17:42:01Z",
    "uaf": {
      "userAgent": "NMASDK/3.3.2.447 (iPhone13,2; iPhoneOS 16.6) ch.nevis.accessapp.muvonda/2.7.20812.812",
      "deviceRef": "be4b7fe8-1785-4818-9550-bb8cd7153fff"
    }
  }
],
"phones": [],
"recoveryCodes": null,
"exceededRateLimits": {
  "push": {
    "resetInSeconds": "120",
    "sent": "10",
    "timeframe": "PT24H"
  }
}
}

404 Not found: No user with provided userId exists.

Retrieve a user by username

HTTP request

GET https://{instance}.mauth.nevis.cloud/api/v1/users?username={username}

Query parameters

Parameter	Type	Required/Optional	Description
`username`	string	required	The custom unique identifier set during the registration of the user.

Example HTTP request

cURL
Python 3

Get user by username
# Set $username
curl "https://$instance.mauth.nevis.cloud/api/v1/users?username=$username" \
  -H "Authorization: Bearer $access_key"

Get user by username
data = {'username':'u12345'}
resp = requests.get(f'https://{instance}.mauth.nevis.cloud/api/v1/users',
                    headers = {'authorization': f'Bearer {access_key}'},
                    params = data)
print(resp.json())

HTTP response

200 OK: User is found.

404 Not found: No user with provided userId exists.

For more information, see the HTTP response section under Retrieve a user by userId.

Delete a user

A user is deleted by their unique, permanent userId. The action also deletes all registered authenticators for this user.

Irreversible Destructive Action

This action is destructive and cannot be reversed.

HTTP request

DELETE https://{instance}.mauth.nevis.cloud/api/v1/users/{userId}

Path parameters

Parameter	Type	Required/Optional	Description
`userId`	UUID	required	Unique identifier of the user to delete.

Example HTTP request

cURL
Python 3

Code sample for deleting a user
# Set $userId
curl "https://$instance.mauth.nevis.cloud/api/v1/users/$userId" \
  -X DELETE \
  -H "Authorization: Bearer $access_key"

Code sample for deleting a user
userId = '7e16ba00-92e2-4fcb-b30e-1af8fdc843aa'
resp = requests.delete(f'https://{instance}.mauth.nevis.cloud/api/v1/users/{userId}',
                       headers = {'authorization': f'Bearer {access_key}'})
print(resp.status_code) # => 204

HTTP response

204 No Content: User and associated authenticators are successfully deleted.

404 Not found: No user with provided userId exists.

No response body is returned in case of successful deletion.

Users endpoint

Retrieve a user by userId​

HTTP request​

Path parameters​

Example HTTP request​

HTTP response​

Example HTTP response​

Retrieve a user by username​

HTTP request​

Query parameters​

Example HTTP request​

HTTP response​

Delete a user​

HTTP request​

Path parameters​

Example HTTP request​

HTTP response​

Retrieve a user by userId

HTTP request

Path parameters

Example HTTP request

HTTP response

Example HTTP response

Retrieve a user by username

HTTP request

Query parameters

Example HTTP request

HTTP response

Delete a user

HTTP request

Path parameters

Example HTTP request

HTTP response