Skip to main content

Approval endpoint

Use this endpoint to start an authentication or approval operation.

HTTP request​

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

Request body parameters​

ParameterTypeRequired/OptionalDescription
usernamestringrequired if userIds is not provided

not required for FIDO2 autofill UI and for usernameless authentication with a mobile app		Represents the user that is the subject of this approval operation.
userIdUUIDrequired if username is not provided

not required for FIDO2 autofill UI and for usernameless authentication with a mobile app		Represents the user that is the subject of this approval operation.
authenticatorIdstringoptionalID of the authenticator to which an approval is sent. The default is the last registered device. The parameter can be set to * to allow any authenticator if channel is set to app.
channelenumrequiredRepresents the authentication channel. You can set it to the following values: app, push, sms, or fido2. For authentication with a mobile app, the default value is push. Set the parameter to app if push is not available or in mobile-only cases.
promptbooleanoptionalFlag to request the user to actively accept or deny the approval. The default value is false. Applicable for authentication with a mobile app.
messagestringrequired when the channel is push or app, and prompt is set to true

optional when the channel is sms		When used with push or app channel, the message is displayed in the mobile app.

When used with sms channel, the message is sent in the SMS. In this case, 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.
notificationMessagestringoptionalNotification message that is displayed on the notification drawer or notification center. The message is only displayed in the mobile app. The parameter is only applicable on push channel.
fido2OptionsDICToptionalProvides customization for the FIDO2 authentication parameters.
fido2Options.userVerificationenumoptionalProvides customization for the user verification requirements. Provides customization preferred, which is the default option, required, or discouraged. For more information, see UserVerificationRequirement.
uafOptionsDICToptionalCustomizes the authentication parameters for FIDO UAF authentication.
uafOptions.visualChannelLinkingenumoptionalSet the parameter to required to enable number matching for push authentication.

Example HTTP requests​

Example requests with a mobile app​

cURL code sample for approval using QR code or deep link
  curl "https://$instance.mauth.nevis.cloud/api/v1/approval" \
    -XPOST \
    -H "Authorization: Bearer $access_key" \
    -H 'Content-Type: application/json' \
    -d "{ \"channel\":\"app\",
          \"username\":\"$username\" }"
Python 3 code sample for approval using QR code or deep link
  data = { 'channel': 'app', 'username': username }
  resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/approval',
                       headers = {'authorization': f'Bearer {access_key}'},
                     json = data)
  print(resp.json())

Example requests with FIDO2​

cURL code sample for approval with custom FIDO2 options
curl "https://$instance.mauth.nevis.cloud/api/v1/approval"  \
  -XPOST \
  -H "Authorization: Bearer $access_key"    \
  -H 'Content-Type: application/json;charset=utf-8'     \
  -d "{ \"username\":\"$username\",
        \"channel\":\"fido2\",
        \"fido2Options\": {
            \"userVerification\":\"required\"
        }
     }"

Example requests with SMS​

cURL code sample for authenticating a transaction with SMS
curl -v -X POST https://$instance.mauth.nevis.cloud/api/v1/approval \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $access_key" \
  -d "{ \"username\":\"$username\",
        \"channel\":\"sms\",
        \"message\":\"SMS Transaction Approval Test, code: {{CODE}}\" }"

HTTP response​

FieldTypeDescription
transactionIdUUIDUnique identifier of this approval operation.
userIdUUIDRepresents the user that is the subject of this approval operation.
statusTokenstringPublishable token that is used to get the status of this approval operation. For more information, see Status endpoint.
qrCodeDICTContains data of the QR code that is used for this approval operation.
qrCode.typestringThe type of the QR code image which is image/png.
qrCode.sizenumberThe size of the QR code image in pixels so that it can be displayed correctly.
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. This field is only applicable to QR codes. 
appLinkUriURIThe URI for mobile-only approval operations using deep links. This field is only applicable to QR codes.
rateLimitInfoDICTContains data about the number of push notifications sent within a time frame. This field is only present if push rate limiting is enabled for your instance.
rateLimitInfo.pushDICTContains the number of push notifications sent and the time frame for the rate limiting.
rateLimitInfo.push.sentstringThe number of push notifications sent in a set timeframe.
rateLimitInfo.push.timeframeISO 8601 durationThe time frame in which the number of sent push notifications are counted. The time frame is relative to the current time.
uafDataDICTContains data related to UAF authentication.
uafData.visualLinkingContentstringRandomly generated two-digit number (01-99) that is displayed on your front end. The two-digit code is used for number matching at push authentication. After the code is displayed, the user can enter it into a mobile app.
credentialRequestOptionsDICTContains options required to authenticate with the WebAuthn credential. Applicable for FIDO2. For more information, see PublicKeyCredentialRequestOptions.
credentialRequestOptions.allowCredentialsarrayContains a list of PublicKeyCredentialDescriptor objects representing public key credentials used for authentication. Applicable for FIDO2.
credentialRequestOptions.allowCredentials.idstringContains the Base64-URL-encoded credential identifier of the public key credential. Applicable for FIDO2.
credentialRequestOptions.allowCredentials.typestringContains the type of the public key credential. Applicable for FIDO2.
credentialRequestOptions.challengestringContains the Base64-URL-encoded challenge that the selected authenticator must sign when producing an authentication assertion. Applicable for FIDO2.
credentialRequestOptions.rpIdstringIdentifier of the relying party. Applicable for FIDO2.
credentialRequestOptions.timeoutlongDefines in milliseconds how much time the call has to complete. Applicable for FIDO2.
credentialRequestOptions.userVerificationenumDescribes the requirements for user verification for authentication. Applicable for FIDO2.

Example HTTP response​

201 Created: Approval with QR Code or deep link

{
  "transactionId": "9ede8ca8-bb5f-47f1-9d3e-f14500a3cab6",
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "statusToken": "eyJhb...lc3g",
  "qrCode": {
    "type": "image/png",
    "size": 300,
    "dataUri": "data:image/png;base64,iVBORw0...U5ErkJggg"
  },
  "appLinkUri": "https://{instance}-app.mauth.nevis.cloud/open?dispatchTokenResponse=eyJub...AQIn3"
}