Skip to main content

Registration endpoint

This endpoint initiates the registration flow, which creates a new authenticator, and if the user does not exists yet, a new user as well.

HTTP request​

POST https://{instance}.mauth.nevis.cloud/api/v1/users/enroll

Request body parameters​

ParameterTypeRequired/OptionalDescription
usernamestringrequired if userId is not provided, or if channel is set to fido2External static identifier to link a user to your systems. The parameter can only contain a-z, A-Z, 0-9, _-.@, and is limited to a maximum of 300 characters.
userIdUUIDrequired if username is not providedRepresents the user that is the subject of this registration operation.
channel stringrequired if the channel is not appRepresents the authentication channel. You can set it to the following values: app, push, sms, fido2, or recovery. If the parameter is omitted, it defaults to app.
messagestringoptionalA message of your choice sent in the SMS. Only GSM-7 character set is supported. The string must contain {{CODE}} as a placeholder for the authentication code. The code is generated by Authentication Cloud. Without the message parameter, a default message is sent. This parameter is only applicable when the channel is sms.
phonestringrequired if channel is set to smsThe phone number that the message is sent to. The number must conform to the international format: [+][country code][area code][local phone number].
displayNamestringrequired if the channel is fido2The human-readable name of the user. The length is limited to 64 bytes.
fido2OptionsDICToptionalProvides customization for the FIDO2 registration parameters.
fido2Options.authenticatorSelectionDICToptionalRestricts the authenticators for registration. For more information, see Authenticator Selection Criteria.
fido2Options.authenticatorSelection.userVerificationenumoptionalProvides customization for the user verification requirements. The parameter values can be preferred, which is the default option, required, or discouraged. For more information, see the UserVerificationRequirement.
fido2Options.authenticatorSelection.authenticatorAttachmentenumoptionalRestricts authenticators based on their attachment modality. The parameter values can be platform or cross-platform. For more information, see Authenticator Attachment.
fido2Options.authenticatorSelection.requireResidentKeybooleanoptionalProvides backwards compatibility with WebAuthn Level 1. The parameter values can be true or false. For more information, see requireResidentKey in Authenticator Selection Criteria.
fido2Options.authenticatorSelection.residentKeyenumoptional Specifies if client-side discoverable credential is to be created. The parameter values can be required, preferred, or the default discouraged. To enable autofill UI for passkeys, use the required value. For more information, see Resident Key Requirement Enumeration.
fido2Options.attestationenumoptionalSpecifies preference regarding attestation conveyance. The parameter values can be none, which is the default option, direct, or indirect. For more information, see Attestation Conveyance Preference Enumeration.

Example HTTP requests​

cURL code sample to register a user with a username for two-way linking
curl "https://$instance.mauth.nevis.cloud/api/v1/users/enroll" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -d "{ \"username\":\"$username\" }"

HTTP response​

FieldTypeDescription
userIdUUIDUnique identifier of the user.
usernamestringThe internal customer ID or unique identifier to link a user to your internal systems. This field 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 authenticator was registered.
updatedAtstringThe date when the authenticator was last updated.
authenticatorsarrayList of the already registered authenticators.
enrollmentDICTContains data of the registration.
enrollment.transactionIdUUIDUnique identifier of this registration operation.
enrollment.statusTokenstringPublishable token that can be used to get the status of this registration operation. For more information, see Status endpoint.
enrollment.qrCodeDICTContains data of the QR code that is used for this registration operation.
enrollment.qrCode.typestringThe type of the QR code image which is image/png.
enrollment.qrCode.sizenumberThe size of the QR code image in pixels so that it can be displayed correctly.
enrollment.qrCode.dataUriURIThe PNG image of the QR code to display for the mobile app to scan. The image can be directly displayed with an <img src="data:image/png..."> tag.
enrollment.appLinkUriURIThe URI for mobile-only registration using deep links.
credentialCreationOptionsDICTThe PublicKeyCredentialCreationOptions object, which contains options required to create a WebAuthn credential.
credentialCreationOptions.attestationstringUsed by the relying party to express preference for attestation conveyance.
credentialCreationOptions.authenticatorSelectionDICTUsed by the relying party to select an appropriate authenticator.
credentialCreationOptions.authenticatorSelection.authenticatorAttachmentstringDescribes the attachment modalities of the authenticators. The value of the field can be platform or cross-platform.
credentialCreationOptions.authenticatorSelection.requireResidentKeybooleanIn the WebAuthn specification Level 1, the field describes the requirements of the relying party regarding resident credentials. Retained for backwards compatibility.
credentialCreationOptions.authenticatorSelection.residentKeystringSpecifies the extent to which the relying party desires to create a client-side discoverable credential.
credentialCreationOptions.authenticatorSelection.userVerificationstringDescribes the requirements for user verification for authentication. Applicable for FIDO2.
credentialCreationOptions.challengestringContains the Base64-URL-encoded challenge for generating the attestation credentials.
credentialCreationOptions.excludeCredentialsarrayIndicates whether the creation of multiple credentials for the account on a single authenticator is limited. By default, this field is empty.
credentialCreationOptions.pubKeyCredParamsarrayContains information about the desired properties of the credential to be created.
credentialCreationOptions.rpDICTDescribes the relying party responsible for the request.
credentialCreationOptions.timeoutlongDefines in milliseconds how much time the call has to complete.
credentialCreationOptions.userDICTStores data about the user account for which the relying party requests attestation.
enrollment.recoveryCodesarrayArray of the 16, newly registered recovery codes.
phonesarrayList of the already registered phone numbers.
recoveryCodesDICTContains information about the already registered recovery codes.

Example HTTP response​

201 Created: Register a mobile app

JSON code sample of a mobile app registration
{
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "username": "u12345",
  "status": "new",
  "createdAt": "2020-10-09T12:13:11.845958Z",
  "updatedAt": "2020-10-09T12:13:11.845958Z",
  "authenticators": [],
  "enrollment": {
    "transactionId": "67cae36e-e3d5-4d67-9aa6-ab7ae3050576",
    "statusToken": "eyJhbGciO...PxOZZYow",
    "qrCode": {
      "type": "image/png",
      "size": 300,
      "dataUri": "data:image/png;base64,iVBO...YII"
    },
    "appLinkUri": "https://{instance}.mauth.nevis.cloud/open?dispatchTokenResponse=eyJub...IxIn0"
  }
}