Skip to main content

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​

ParameterTypeRequired/OptionalDescription
userIdUUIDrequiredUnique identifier of the user to retrieve.

Example HTTP request​

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

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.

FieldTypeDescription
userIdUUIDUnique identifier of this user.
usernamestringThe internal customer ID or unique identifier to link a user to your internal systems. The value can be null.
statusenumThe 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.
createdAtstringThe date when the user was created.
updatedAtstringThe date when the user was last updated.
lastLoginDateSuccessstringThe date of the last successful login with this user.
lastLoginDateFailurestringThe date of the last failed login with this user.
authenticatorsarrayList of the already registered authenticators.
authenticators.authenticatorIdUUIDUnique identifier of the authenticator.
authenticators.namestringThe name of the authenticator provided by the user.
authenticators.typeenumDefines the mobile platform for mobile app authenticators. The value is ios for iOS, and android for Android.
authenticators.authenticatorTypeenumDetermines the type of the authenticator. The value can be appor fido2.
authenticators.stateenumIndicates the state of the authenticator.
authenticators.enrolledAtstringThe date when the authenticator was registered.
authenticators.updatedAtstringThe date when the authenticator was last updated.
authenticators.uafDICTIf present, this field contains data related to the FIDO UAF authenticator. Only applicable if the authenticatorType is app.
authenticators.uaf.userAgentstringOptional user agent. The client application sends the userAgent when a FIDO UAF authenticator is registered or used for authentication.
authenticators.uaf.deviceRefUUIDUnique 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.userDisabledPushNotificationbooleanIndicates if a user is disabled (true) or enabled (false) notifications for their application. When disabled, push authentication is not possible.
authenticators.fido2DICTContains FIDO2-specific information of the authenticator. Only applicable if the authenticatorType is fido2.
authenticators.fido2.userAgentstringOptional 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.rpIdstringThe identifier in FIDO2 integration prerequisites, for which the authenticator is registered.
authenticators.fido2.aaguidstringThe Authenticator Attestation Globally Unique Identifier, a unique number that indicates the type (for example, make and model) of the authenticator.
authenticators.fido2.userVerificationRequirementenumDescribes 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.attestationConveyancePreferenceenumSpecifies 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.residentKeyRequirementenumDescribes 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.
authenticators.lastLoginDateSuccessstringThe date of the last successful login with this authenticator.
authenticators.lastLoginDateFailurestringThe date of the last failed login with this authenticator.
phonesarrayList of successfully registered phone numbers.
phones.authenticatorIdUUIDUnique identifier of the authenticator.
phones.namestringThe name of the phone provided by the user.
phones.authenticatorTypeenumDetermines the type of the authenticator. The value is sms.
phones.stateenumIndicates the state of the phone authenticator.
phones.enrolledAtstringThe date when the phone was registered.
phones.updatedAtstringThe date when the phone was last updated.
phones.phoneNumberstringThe actual registered phone number, masked to avoid personally identifiable information.
recoveryCodesDICTContains information about the registered recovery codes.
recoveryCodes.validFromstringThe date from which the recovery codes are valid.
recoveryCodes.validTostringThe date until the recovery codes are valid.
recoveryCodes.stateenumIndicates 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.codesarrayList of the 16 registered recovery codes.
recoveryCodes.codes.indexnumberProvides an index for the list of recovery codes. The value ranges from 0 to 15.
recoveryCodes.codes.usedAtstringThe date when the recovery code was used for authentication. The value of the field for unused recovery codes is null.
recoveryCodes.lastLoginDateSuccessstringThe date of the last successful login with recovery codes.
recoveryCodes.lastLoginDateFailurestringThe date of the last failed login with recovery codes.
exceededRateLimitsDICTIndicates 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.pushDICTContains data of the push rate limit.
exceededRateLimits.push.resetInSecondsstringIndicates 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.sentstringThe number of push notifications sent in set timeframe.
exceededRateLimits.push.timeframeISO 8601 durationThe time frame in which the number of sent push notification are counted. The time frame is relative to the current time.
note

The lastLoginDateSuccess and lastLoginDateFailure fields are only updated on FIDO2 authenticators and recovery codes.

Example HTTP response​

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
}

Retrieve a user by username​

HTTP request​

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

Query parameters​

ParameterTypeRequired/OptionalDescription
usernamestringrequiredThe custom unique identifier set during the registration of the user.

Example HTTP request​

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

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​

ParameterTypeRequired/OptionalDescription
userIdUUIDrequiredUnique identifier of the user to delete.

Example HTTP request​

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"

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.