Welcome to the Authentication Cloud API

This API documentation explains in detail how to create the right HTTP requests for calling the Authentication Cloud API endpoints, listing all available parameters, HTTP requests and responses.

Add passwordless authentication and transaction signing to your own applications and services with just a few REST API calls to our Authentication Cloud API. Moreover, the Authentication Cloud also offers various additional authentication factors, like SMS or Recovery Codes. For more details about the Nevis Authentication Cloud, see our documentation.

In this pane we provide examples for both cURL and Python 3.

# Make sure you have curl installed:
curl --version

# Set your instance id and securely paste your access key:
instance=your-instance-id-abc123
read -s access_key
export instance access_key

# Requires Python 3 and the requests library: pip install requests
# Make sure this works:
import requests

# Set your instance id and securely read your access key:
instance = 'your-instance-id-abc123'
access_key = ...

When you sign up for the service, you can use the Management Console to obtain the API endpoint URL and generate an authorization token for the machine-to-machine communication with your Nevis Auth Cloud.

Endpoint

The Authentication Cloud API is organized around REST and has predictable resource-oriented URLs. The base URL for your instance is as follows:

https://{instance}.mauth.nevis.cloud/

curl "https://$instance.mauth.nevis.cloud/ping" \
  -H "Authorization: Bearer $access_key"

resp = requests.get(f'https://{instance}.mauth.nevis.cloud/ping',
                    headers = {'authorization': f'Bearer {access_key}'})
print(resp.text) # => PONG

Authentication

The Authentication Cloud API uses access keys to authenticate requests. You can view and manage your access keys in the Management Console under Custom Integrations. Authentication Cloud expects the access key to be included in all API requests to the server in a header as the following:

Authorization: Bearer {access_key}

• All calls to the API must be authenticated using an Authorization Bearer Token header.
• All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
• API requests without authentication will also fail.

Intent tokens

An Intent token is a short-living one-time token, that is restricted to a specific user and a specific intent. On some endpoints, you can send an intent token in the Authorization Bearer Token header instead of sending the Access Key. See Integrating the Widget for more details on intent tokens.

Media Type

Throughout the API we use the following media types:

Accept: application/json
Content-Type: application/json;charset=utf-8

Our API accepts JSON-encoded request bodies, returns JSON-encoded responses. It also uses standard HTTP response codes, authentication, and verbs. If an endpoint expects a different content type, it's highlighted within the documentation.

Versioning

We release new versions of the API in a backwards-compatible way. You can expect the same version, noted in the URL, to return the same information even over time. New features are added either as new fields, options, or exposed as different resources. The API endpoint is at https://{instance}.mauth.nevis.cloud/api/v1/, the versioning scheme currently used is v1.

Current API Scheme: v1

Errors

403 Forbidden: Invalid access token provided

{
    "error": "Forbidden",
    "path": "/api/v1/users/enroll",
    "status": 403,
    "timestamp": 1600863157593
}

400 Bad Request: Request body wasn't JSON-encoded

{
    "error": "Bad Request",
    "message": "Required request body ...",
    "path": "/api/v1/users/enroll",
    "status": 400,
    "timestamp": "2020-09-23T12:13:45Z",
}

400 Bad Request: Validation error

{
    "error": "Bad Request",
    "message": "The username '%%%%%' contains invalid characters ...",
    "path": "/api/v1/users/enroll",
    "status": 400,
    "timestamp": "2020-09-23T12:15:23Z",
}

The REST API provides consistent, predictable error reporting, with HTTP status codes and detailed error messages.

The following error codes may be returned:

Enroll users

The first step is to enroll an authentication factor for a user. The following is a typical enrollment flow:

1. Your users open the login page of your application.
2. They enter existing credentials, usually username and password. This is checked against your existing identity management system.
3. If this login step is successful, your system calls the Nevis Authentication Cloud API to enroll the user. A QR code is returned in the response that can be displayed as part of your new login process. Users will need to use the Access App to scan the code.
4. In the meantime, the system starts to poll the status endpoint to see whether the user completes the registration.
5. The user downloads the Access App and scans the QR code to complete the registration of their authenticator.
6. The Access App sends the confirmed registration directly back to the Nevis Authentication Cloud.
7. The polling continues until it returns either "status": "succeeded" in the JSON response, indicating that the user successfully registered, or it returns an error.

From now on, the user can use the Access App to perform any authentication operation without using a password.

Enroll Your Access App

Enroll a new user for the Access App without a username. This always creates a new user.

curl "https://$instance.mauth.nevis.cloud/api/v1/users/enroll" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -d '{}'

resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/users/enroll',
                     headers = {'authorization': f'Bearer {access_key}'},
                     json = {})
print(resp.json())

The simplest case is enrolling a new user without any additional arguments. The code sample on the side initiates the registration flow that must be confirmed. Note that it does not contain a username, but the response returns a unique userId that identifies the user for the entire life cycle.

This endpoint starts enrollment for the Access App.

Link user with username

Enroll 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": "u12345" }'

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

We recommend using unique static information as the username for enrollment. To link a user to your internal systems, you may use, for example, an internal customer ID or employee ID, and provide that as a username in the user enrollment request. It is important to use information which is static and does not change over the life cycle of a user.

We also recommend using a username without any personally identifiable information (PII). A bad example would be to use the e-mail address, as this is not only PII data, but may also change over the lifecycle of a user.

HTTP Request

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

Headers

You can send an intent token in the Authorization Bearer Token header, instead of sending the Access Key. See Integrating the Widget for more details on intent tokens.

Parameters

HTTP Response

201 Created: Enroll Access App

{
  "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"
  }
}

See User for the documentation of all user attributes, like username or authenticators.

The enrollment response always contains an enrollment object with the following fields:

Enroll Your Phone Number

Request Your SMS Code for Enrollment

Set your username and phone variables. The username can be any alphanumeric string of no more than 300 characters, while the phone should be your phone number in the international format.

curl -X POST https://$instance.mauth.nevis.cloud/api/v1/users/enroll \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $access_key" \
  -d "{ \"username\":\"$username\", \"channel\":\"sms\", \"message\":\"SMS Registration Test, code: {{CODE}}\", \"phone\":\"$phone\" }"

Enrolling a phone number enables your users to register for second factor authentication using only a phone number and any low-end mobile device. It means that mTAN via SMS is used as the second factor in addition to their existing authentication process, such as a username and password.

Prerequisites

• You have an active SMS subscription enabled and configured on your account. Contact us for details.

HTTP Request

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

Headers

You can send an intent token in the Authorization Bearer Token header, instead of sending the Access Key. See Integrating the Widget for more details on intent tokens.

Parameters

HTTP Response

{
    "authenticators": [],
    "createdAt": "2021-06-28T11:53:33.312492Z",
    "enrollment": {
        "statusToken": "eyJhbGciiJ9.ey..._ZQ6D8tw",
        "transactionId": "4bb078e1-...-20ee97eaca2d"},
    "phones": [],
    "recoveryCodes": null,
    "status": "new",
    "updatedAt": "2021-06-28T11:53:33.312493Z",
    "userId": "02c14dba-bdb2-...-9474c59a40d1",
    "username": "TestUser"
}

The enrollment response contains an enrollment object with the following fields:

Verifying the Registration

Set your statusToken, userId and the registration code variables. The userId and the statusToken are returned as JSON object members by the previous API call. The code is the mTAN delivered to your phone as an SMS.

curl -v -X POST https://$instance.mauth.nevis.cloud/api/v1/users/$userId/verification \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $access_key" \
  -d "{ \"code\":\"$code\", \"statusToken\":\"$statusToken\" }"

HTTP Request

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

Parameters

HTTP Response

HTTP/1.1 200 OK

The response is either an HTTP/1.1 200 if the verification is successful, or an HTTP/1.1 4xx otherwise.

Enroll for Recovery Codes

Enroll to Request Your Recovery Codes

Set your username variable. The username must be that of the user who requires emergency authentication.

curl -v -X POST https://$instance.mauth.nevis.cloud/api/v1/users/enroll \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $access_key" \
  -d "{ \"username\":\"$recovery_username\", \"channel\":\"recovery\" }"

Enrolling for recovery codes provides your existing users with a fallback authentication method in case they lose or damage their mobile phone. Recovery codes are a set of static 16-digit, alphanumeric, case-sensitive codes. Each can be used once for emergency authentication.

HTTP Request

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

Headers

You can send an intent token in the Authorization Bearer Token header, instead of sending the Access Key. See Integrating the Widget for more details on intent tokens.

Parameters

HTTP Response

A set of sixteen recovery codes is returned as part of the enrollment data. Each code may be used only once. If a new batch is requested, all previous codes become invalid.

{
    "authenticators": [],
    "createdAt": "2021-07-05T07:57:12.184902Z",
    "enrollment": {
        "recoveryCodes": [
            "3YL2-...-PnZh",
            "4B90-...-fgF2",
            ...
            "YTbB-...-lCI0"
        ],
        "transactionId": "bec412cc-...-d2cb24bac64b"
    },
    "phones": [],
    "recoveryCodes": null,
    "status": "new",
    "updatedAt": "2021-07-05T07:57:12.184904Z",
    "userId": "2eda9f3c-...-a897e3bf0b7c",
    "username": "testUser20210702C"
}

The enrollment response contains an enrollment object with the following fields:

Enroll with FIDO2

The endpoint starts the enrollment for a FIDO2-capable device.

Enrolling the device

Enroll with a username that uniquely identifies your user.

curl "https://$instance.mauth.nevis.cloud/api/v1/users/enroll" \
  -XPOST \
  -H "Authorization: Bearer $access_key"  \
  -H 'Content-Type: application/json;charset=utf-8'   \
  -d '{ "username": "u_12654",
        "channel": "fido2",
        "displayName": "John Doe"
      }'

Use a unique static information as the username for enrollment. This can be used to link the user to your internal systems. An internal customer ID or employee ID, as a username can be added to the user enrollment request. It is important to use information which is static and does not change over the life cycle of a user.

We also recommend using a username without any personally identifiable information (PII). A bad example would be to use the e-mail address, as this is not only PII data, but may also change over the lifecycle of a user.

Enrolling the device with custom FIDO2 options

To change the default enrollment settings, you can extend the usual username, displayName, and channel by optional fido2Options.

curl "https://$instance.mauth.nevis.cloud/api/v1/users/enroll" \
  -XPOST \
  -H "Authorization: Bearer $access_key"  \
  -H 'Content-Type: application/json;charset=utf-8'   \
  -d '{ "username": "u_12654",
        "channel": "fido2",
        "displayName": "John Doe",
        "fido2Options": {
            "authenticatorSelection": {
                "userVerification": "required",
                "authenticatorAttachment": "platform",
                "requireResidentKey": false,
                "residentKey": "discouraged"
            },
            "attestation": "none"
        }
      }'

HTTP Request

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

Headers

You can send an intent token in the Authorization Bearer Token header, instead of sending the Access Key. See Integrating the Widget for more details on intent tokens.

Parameters

HTTP Response

201 Created: Enroll FIDO2 device

{
    "authenticators": [],
    "createdAt": "2022-03-04T11:04:51.523566769Z",
    "enrollment": {
        "credentialCreationOptions": {
            "attestation": "none",
            "authenticatorSelection": {
                "authenticatorAttachment": "platform",
                "requireResidentKey": false,
                "residentKey": "discouraged",
                "userVerification": "required"
            },
            "challenge": "h6U-j...PUrw",
            "excludeCredentials": [],
            "pubKeyCredParams": [
                {
                    "alg": -65535,
                    "type": "public-key"
                },
                ...
                {
                    "alg": -36,
                    "type": "public-key"
                }
            ],
            "rp": {
                "id": "your-nevis-dev.mauth.nevis.cloud",
                "name": "NEVIS Authentication Cloud: your-nevis-dev"
            },
            "timeout": 60000,
            "user": {
                "displayName": "John Doe",
                "id": "ZmY0Mj...1YTky",
                "name": "u_12654"
            }
        },
        "statusToken": "eyJh...9.eyJh...ZQI-MuCQ",
        "transactionId": "e7bf20-...-56b6683"
    },
    "phones": [],
    "recoveryCodes": null,
    "status": "new",
    "updatedAt": "2022-03-04T11:04:51.523567669Z",
    "userId": "ff4-a...d5a92",
    "username": "u_12654"
}

See User for the documentation of all user attributes, like username or authenticators.

The registration response always contains an enrollment object with the following fields:

Next steps

If you use FIDO2 from web browser, continue with Register the device.

Finalize registration

If you use FIDO2 in native mobile application, use the response of the enrollment endpoint to register the WebAuthn credential on the client side.

For more information on WebAuthn registration on iOS, see Public-Private Key Authentication.

When the WebAuthn credential registration is completed on the client side, send the PublicKeyCredential object to finalize the registration.

Finalize the registration

curl "https://$instance.mauth.nevis.cloud/_app/attestation/result" \
  -XPOST \
  -H 'Content-Type: application/json;charset=utf-8'   \
  -H 'Accept: application/json' \
  -d '{
    "id": "F4xhFr...o8g",
      "type": "public-key",
      "response": {
          "attestationObject": "o2NmbX...6_N-IvQ",
          "clientDataJSON": "eyJjaG...YXRlIn0"
      },
      "statusToken": "eyJh...W4vg",
      "userFriendlyName": "A user-friendly name can be added for the authenticator",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64; rv:104.0) Gecko/20100101 Firefox/104.0"
    }'

HTTP Request

POST https://{instance}.mauth.nevis.cloud/_app/attestation/result

Headers

The endpoint requires no Authorization Bearer Token header.

Parameters

Note that some HTTP request parameters have to be Base64 URL-encoded.

HTTP Response

200 OK: Success response

{
  "errorMessage": "",
  "status": "ok",
  "token": "eyJhbGc...2CDSw"
}

200 OK: Failure response

{
  "errorMessage": "The server could not process the WebAuthn message.",
  "status": "failed",
  "token": "eyJh...haqvw"
}

Authenticate and Approve

After a user's status becomes active and thus has at least one registered authenticator, it is possible to start an authentication or transaction approval for that user. The exact same process can be used for both login and any other transaction approval.

Similar to enrollments, an approval process is always split into two REST API calls:

1. Start the approval process with a message and other details about the approval.
2. Keep polling the authenticator for a change in the approval status.

The approval request, as part of a second-factor login using the Access App and QR-code login, is explained below. Polling is explained subsequently in Polling for the Status.

1. Your user opens the login page of your application.
2. The user enters their existing credentials, usually a username and a password. This is checked against the existing systems of the provider.
3. After a successful login, the system triggers an approval REST API call. This call may contain a custom message, such as: "New login request to your business application".
4. You start polling for approval by the user.
5. The Nevis Authentication Cloud creates a QR code to be scanned by the user's mobile device.
6. The user scans the QR code with the Access App.
7. The user confirms the approval to "New login request to your business application" using their fingerprint scan or face recognition. The user may also deny a request if they did not initiate the login.
8. The cryptographically signed confirmation is directly sent back to the cloud service.
9. In the meantime, the regular polling continues, and it now returns "status": "succeeded", indicating that the user did indeed approve the request. The system then logs the user in and forwards the user to the application.

Authenticate using the Access App

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": "u12345" }'

data = { 'channel': 'app', 'username': 'u12345' }
resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/approval',
                     headers = {'authorization': f'Bearer {access_key}'},
                     json = data)
print(resp.json())

By default, the approval endpoint uses push notifications for approvals and confirmations. To use QR code or deep link, you can provide the channel parameter in the JSON body:

• app recommended: Provides a QR code and a deep link. No push notification is sent in this case.
• push: Transmits the approval as a push notification to the authenticator. As a prerequisite on Android devices, the user has to have Google Play Services installed.

Approve using push

Approval using push:

curl "https://$instance.mauth.nevis.cloud/api/v1/approval" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -d '{ "channel": "push", "username": "u12345",
        "message": "Login request for example.com"
        "notificationMessage": "Login request" }'

data = { 'channel': 'push', 'username': 'u12345',
         'message': 'Login request for example.com' }
resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/approval',
                     headers = {'authorization': f'Bearer {access_key}'},
                     json = data)
print(resp.json())

If your users cannot receive push notifications on their mobile phones, QR codes are an alternative means for authentication.

Request in-app user confirmation

Request in-app user confirmation:

curl "https://$instance.mauth.nevis.cloud/api/v1/approval" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -d '{ "channel": "app", "prompt": "true", "username": "u12345",
        "message": "Login request for example.com" }'

data = { 'channel': 'app', 'prompt': True, 'username': 'u12345',
         'message': 'Login request for example.com' }
resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/approval',
                     headers = {'authorization': f'Bearer {access_key}'},
                     json = data)
print(resp.json())

Rather than only asking for biometric confirmation, with the flag "prompt": true the user is shown the full message within the app, and they either approve or deny that request.

Text Formatting

You can format the transaction confirmation text (the message field) with a limited set of supported HTML tags. To enable text formatting, enclose the transaction confirmation text in the HTML tags <html></html>. The following tags and formatting options are supported:

• bold: <b></b>
• line break: <br>
• emphasis: <em></em>
• italic: <i></i>
• strong: <strong></strong>
• underline: <u></u>

Approval with any authenticator

Approval with allowing any authenticator:

curl "https://$instance.mauth.nevis.cloud/api/v1/approval" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -d '{ "channel": "app", "username": "u12345", "authenticatorId": "*" }'

Rather than starting an approval with a specific authenticator or the default (last registered) device, the user can authenticate with any registered authenticator of the user. For an approval with any authenticator, set the channel parameter to app.

Usernameless authentication

Usernameless approval request:

curl "https://$instance.mauth.nevis.cloud/api/v1/approval" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -d '{ "channel": "app" }'

Usernameless authentication allows the convenience to your users authenticate without providing their username or userId. For usernameless authentication, set the channel parameter to app.

HTTP Request

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

Headers

You can send an intent token in the Authorization Bearer Token header, instead of sending the Access Key. See Integrating the Widget for more details on intent tokens.

Parameters

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"
}

201 Created: Approval using push

{
  "transactionId": "e7c4328a-5497-4768-ac49-471db85defd4",
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "statusToken": "eyJhb...CGJNfkA"
}

The response is slightly different, depending on the channel used for the approval.

Authenticate with SMS

Once your phone number has been registered, you can use an mTAN as a second factor to authenticate a transaction. For example, in case of a login, after processing the usual username and password, you send a text message with a one-time code to the user's mobile to provide a second factor for authentication.

Prerequisites

• You have an active SMS subscription enabled and configured on your account. Please contact us for details.
• The user account has been successfully registered for SMS.

Request an SMS Code for Authentication

NOTE: Set your username and access_key variables.

Authenticate a transaction

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 Request

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

Headers

You can send an intent token in the Authorization Bearer Token header, instead of sending the Access Key. See Integrating the Widget for more details on intent tokens.

Parameters

HTTP Response

{
    "statusToken": "eyJhbGciOiJIUzUxMiJ9.eyJhd...hInHRfSw",
    "transactionId": "d9db4760-...-5cbe533389e3",
    "userId": "7a342fb4-...-bb837ed32d9d"
}

The response for the sms channel returns a status token that can be used for the verification of the transaction.

Verify the Code

Set your userId, code and the statusToken variables.

curl -v -X POST https://$instance.mauth.nevis.cloud/api/v1/users/$userId/verification \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $access_key" \
  -d "{ \"code\":\"$code\", \"statusToken\":\"$statusToken\" }"

HTTP Request

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

Parameters

HTTP Response

HTTP/1.1 200 OK

The response is either an HTTP/1.1 200 if the verification is successful, or an HTTP/1.1 4xx otherwise.

Authenticate with Recovery Codes

Set your code and userId variables. The userId must be the ID of the recovery_username you set previously when you enrolled for recovery codes.

curl -v https://$instance.mauth.nevis.cloud/api/v1/users/$userId/verification \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $access_key" \
    -d "{ \"code\":\"$code\", \"channel\":\"recovery\" }"

As a fall-back recovery mechanism, users can use any of their previously generated recovery codes to authenticate a transaction. To generate a set of recovery codes, see the section on enrolling for recovery codes.

You need the userId for this specific authentication channel.

HTTP Request

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

Parameters

HTTP Response

HTTP/1.1 200 OK

The response is either an HTTP/1.1 200 if the verification is successful, or an HTTP/1.1 4xx otherwise.

Authenticate with a FIDO2 authenticator

Approval with default 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": "u_12654",
        "channel": "fido2"
      }'

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": "u_12654",
        "channel": "fido2",
        "fido2Options": {
            "userVerification": "required"
        }
      }'

The endpoint starts the authentication for a FIDO2-capable device.

HTTP Request

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

Headers

You can send an intent token in the Authorization Bearer Token header, instead of sending the Access Key. See Integrating the Widget for more details on intent tokens.

Parameters

HTTP Response

201 Created: Approval using a FIDO2 device

{
  "statusToken": "eyJ...iJ9.ey...fVag0LMfTMX5kQ",
  "transactionId": "8b2373-...-9698e35e",
  "userId": "d517-...-7cb4521b3",
  "credentialRequestOptions": {
    "allowCredentials": [
      {
        "id": "hZAe...aNBS7rX8jBY",
        "type": "public-key"
      }
    ],
    "challenge": "2LpI-1C...drA",
    "rpId": "nevis-latest-dev-cbbc98.mauth.nevis.cloud",
    "timeout": 60000,
    "userVerification": "required"
  }
}

Next steps

If you use FIDO2 from the web browser, continue with Authenticate using FIDO2.

Finalize authentication

If you use FIDO2 in a native mobile application, use the response of the approval endpoint to authenticate with the WebAuthn credential on the client side.

For more information on WebAuthn authentication on iOS, see Public-Private Key Authentication.

When the authentication with the WebAuthn credential is completed on the client side, send the PublicKeyCredential object to finalize the authentication.

Finalize the authentication

curl "https://$instance.mauth.nevis.cloud/_app/assertion/result" \
  -XPOST \
  -H 'Content-Type: application/json;charset=utf-8'   \
  -H 'Accept: application/json' \
  -d '{
    "id": "vytTk...uaQ",
    "type": "public-key",
    "response": {
        "authenticatorData": "bzmK...CA",
        "clientDataJSON": "eyJjaGFs...Z2V0In0",
        "signature": "MEUC...idDMiY",
        "userHandle": "ZWNjZ...MjM4"
    },
    "statusToken": "eyJhbG...ccG3eQ",
    "userAgent": "Mozilla/5.0 (X11; Linux x86_64; rv:104.0) Gecko/20100101 Firefox/104.0"
  }'

HTTP Request

POST https://{instance}.mauth.nevis.cloud/_app/assertion/result

Headers

The endpoint requires no Authorization Bearer Token header.

Parameters

Note that some HTTP request parameters have to be Base64 URL-encoded.

HTTP Response

200 OK: Success response

{
  "errorMessage": "",
  "status": "ok",
  "token": "eyJhbGc...2CDSw"
}

200 OK: Failure response

{
  "errorMessage": "The server could not process the WebAuthn message.",
  "status": "failed",
  "token": "eyJh...haqvw"
}

Verify an operation

Using the statusToken received in enrollment or approval call responses, you can poll for the status of the operation.

Status polling

Poll for the status as long as status is pending:

# Set $statusToken
curl "https://$instance.mauth.nevis.cloud/api/v1/status" \
  -XPOST \
  -H 'Content-Type: application/json' \
  -d "{ \"statusToken\": \"$statusToken\" }"

data = {'statusToken': 'eyJhb...lc3g'}
resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/status', json = data)
print(resp.json())

When the polling is completed on the client side (user), then there are two ways to verify a transaction:

• By checking the token against the Token Verification Endpoint, and reading the status from the token body, or
• By calling the status endpoint again from the server side

Get the userId with usernameless authentication

In case of Usernameless authentication, you can use the status endpoint to get the identifier of the authenticated user. Since in this case the user is not known until the authentication is successfully finished, the intermediate status responses do not contain a userId. After the user is successfully authenticated, the userId is included in the status response.

HTTP request

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

Parameters

HTTP response

200 OK: Pending - The transaction is still waiting for confirmation by the user

{
  "transactionId": "b7d44592-91f3-4f4b-9e37-202a3061edc3",
  "status": "pending",
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "token": "eyJhb...Fl9bpEXGGw",
  "createdAt": "2020-10-09T12:52:48Z",
  "lastUpdatedAt": "2020-10-09T12:52:48Z"
}

200 OK: Succeeded - The transaction was successfully confirmed by the user

{
  "transactionId": "b7d44592-91f3-4f4b-9e37-202a3061edc3",
  "status": "succeeded",
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "token": "eyJhb...Fl9bpEXGGw",
  "createdAt": "2020-10-09T12:52:48Z",
  "lastUpdatedAt": "2020-10-09T12:52:48Z"
}

412 Precondition Failed: The transaction was aborted or timed out

{
  "transactionId": "b7d44592-91f3-4f4b-9e37-202a3061edc3",
  "status": "failed",
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "token": "eyJhb...Fl9bpEXGGw",
  "createdAt": "2020-10-09T12:52:48Z",
  "lastUpdatedAt": "2020-10-09T12:52:48Z"
}

404 Not Found: The provided status token is not known

{
  "status": "unknown"
}

You can then check for the status and react accordingly:

• pending: The transaction is still pending, either the user did not see the push notification yet, or did not react to it yet.
• succeeded: The transaction was successful.
• failed: The transaction failed, either by timeout or because the user did not accept.
• unknown: Unknown transaction.

Check token validity

Check the validity and authenticity of a token:

# Set $token
curl "https://$instance.mauth.nevis.cloud/api/v1/introspect" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  --data-urlencode "token=$token"

data = {'token': 'eyJhb...lc3g'}
resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/introspect',
                     headers = {'authorization': f'Bearer {access_key}'},
                     data = data)
print(resp.json())

Use the introspect API endpoint to check whether a token is valid, and whether the token was actually issued by your Authentication Cloud instance. You can use the endpoint to verify the authenticity of transaction tokens after successful authentications, especially in cases like in-band operations.

Supported tokens

The following tokens are supported by the introspect endpoint:

• API key: Also mentioned as access key. Used for authenticating API requests from server side. See the Authentication for details.
• Transaction token: Returned by the Status endpoint. Use this token to verify whether the operation was really executed by your Authentication Cloud instance.
• Status token: Returned by starting an enrollment or approval operation. Use this token to get the status of the enrollment or approval operation with the Status endpoint.
• Intent token: Short-living one-time token which is restricted to specific user and specific intent. See the Integrating the Widget for details.

HTTP request

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

Parameters

HTTP response

200 OK: Active and valid API key

{
  "active": true,
  "iat": 1642436165000,
  "sub": "c8edb1d1-6dac-470f-b2fb-c25277a5c5b6",
  "aud": "api",
  "iss": "https://{instance}.mauth.nevis.cloud/"
}

200 OK: Valid transaction token

{
  "active": true,
  "iat": 1654759374000,
  "sub": "fc6bf4bb-9f46-48a9-95d6-91051a3d6468",
  "aud": "transaction",
  "iss": "https://{instance}.mauth.nevis.cloud/"
}

200 OK: Valid status token

{
  "active": true,
  "iat": 1662625372000,
  "sub": "29886449-532e-4de7-923d-845e94b81762",
  "aud": "status",
  "iss": "https://{instance}.mauth.nevis.cloud/",
  "jti": "fdc3e23e-9ec8-4375-9b13-9a586270a9cd"
}

200 OK: Valid intent token

{
  "iat": 1662626062,
  "exp": 1662626662,
  "aud": "intent",
  "iss": "https://{instance}.mauth.nevis.cloud/",
  "sub": "0afb658e-9536-430f-a69b-d53a7a603be1",
  "scope": "enroll:sms,app"
}

200 OK: Invalid token

{
  "active": false
}

Users and Authenticators

The primary resources within the Nevis Authentication Cloud are users, and authenticators, such as our brandable Access App.

User

Example user resource

{
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "username": "u12345",
  "status": "active",
  "createdAt": "2020-06-16T16:42:44Z",
  "updatedAt": "2020-06-16T16:42:44Z",
  "authenticators": [
    ...
  ],
  "phones": [
    ...
  ],
  "recoveryCodes": null
}

User with registered recovery codes

{
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "username": "u12345",
  "status": "active",
  "createdAt": "2020-06-16T16:42:44Z",
  "updatedAt": "2020-06-16T16:42:44Z",
  "authenticators": [
    ...
  ],
  "phones": [
    ...
  ],
  "recoveryCodes": {
    "validFrom": "2022-11-25T07:59:17Z",
    "validTo": "2032-11-22T07:59:17Z",
    "state": "active",
    "codes": [
      {
        "index": 0,
        "usedAt": "2022-11-25T08:01:45Z"
      },
      {
        "index": 1,
        "usedAt": null
      },
      {
        "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
      }
    ]
  }
}

The user is the primary resource in the Authentication Cloud, and has a 1:1 mapping to user objects within your existing identity management system.

Recovery codes can have the following state:

• initial: The user successfully registered a set of recovery codes and none of the codes were used.
• active: The user authenticated a transaction with at least one recovery code.

Authenticator

The authenticator resource can represent:

• an Access App, or
• a FIDO2-capable device.

Access App authenticator

Example Access App authenticator object

{
  "authenticatorId": "f3ef70fc-9231-48f8-8e81-8eef7826d594",
  "name": "Anna's iPhone X",
  "type": "ios",
  "authenticatorType": "app",
  "state": "active",
  "enrolledAt": "2020-10-09T08:44:36Z",
  "updatedAt": "2020-10-09T08:44:36Z"
}

The Access App authenticator is based on the FIDO UAF protocol. This is both available as a native, brandable iOS or Android application - or for integration into existing business apps, as a native SDK for both platforms.

authenticator refers to the mobile device enrolled for the user.

During the lifetime of a user, it may be necessary to replace their existing authenticator, that is, their mobile phone, so that they can continue accessing your systems using passwordless authentication. Use the enrollment requests and provide an existing userId or username in the process.

FIDO2 authenticator

The FIDO2 authenticator represents a FIDO2 / WebAuthn capable device. The FIDO2 authenticator can be a roaming authenticator (for example, YubiKey), or a platform authenticator (for example, a Windows 10 device with Windows Hello, or a MacBook with Touch ID).

Example FIDO2 authenticator object

{
  "authenticatorId": "ee46aeca-0419-43a4-be12-a652c0ac48a8",
  "name": "My MacBook",
  "authenticatorType": "fido2",
  "state": "active",
  "enrolledAt": "2022-02-14T15:56:37Z",
  "updatedAt": "2022-02-14T15:56:57Z",
  "fido2": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.82 Safari/537.36",
    "rpId": "yourinstance.mauth.nevis.cloud",
    "aaguid": "08987058-cadc-4b81-b6e1-30de50dcbe96",
    "userVerificationRequirement": "preferred",
    "attestationConveyancePreference": "direct",
    "residentKeyRequirement": "discouraged"
  }
}

Phone Number

Phone numbers are used for sending mTAN via SMS. Phone number information is part of the user response.

See Enroll Your Phone Number for more information.

Example Phone Number authenticator object

{
  "authenticatorId": "16b25cdd-fc52-4827-8e2c-600e462db61d",
  "name": "+362***12",
  "authenticatorType": "sms",
  "state": "active",
  "enrolledAt": "2022-11-25T08:04:23Z",
  "updatedAt": "2022-11-25T08:08:44Z",
  "phoneNumber": "+362***12"
}

Retrieve a user

Get user by userId

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

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())

You can search for users by userId, or alternatively also by username.

Use the enrollment endpoint to create a new user.

HTTP Request

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

Parameters

HTTP Response

200 OK: User is found.

404 Not found: No user with provided userId exists.

For the details of the response, see User.

Retrieve user by username

Get user by username

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

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())

You can directly look up a user by your own unique identifier defined during the enrollment of the user.

HTTP Request

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

Parameters

HTTP Response

200 OK: User is found.

404 Not found: No user with provided userId exists.

For the details of the response, see User.

Delete a user

Delete a user

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

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

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

HTTP Request

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

Parameters

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.

Rename an authenticator

Change authenticator name

# Set $authenticator_id
curl "https://$instance.mauth.nevis.cloud/api/v1/authenticators/$authenticator_id" \
  -X PATCH \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Personal Phone" }'

authenticator_id = 'f3ef70fc-9231-48f8-8e81-8eef7826d594'
data = {'name':'Personal Phone'}
resp = requests.patch(f'https://{instance}.mauth.nevis.cloud/api/v1/authenticators/{authenticator_id}',
                      headers = {'authorization': f'Bearer {access_key}'},
                      json = data)
print(resp.json())

As device names can be rather non-descriptive, users may want to change the name of the mobile phone they use as an authenticator. They can do this using the authenticators API endpoint.

HTTP Request

PATCH https://{instance}.mauth.nevis.cloud/api/v1/authenticators/{authenticatorId}

Parameters

HTTP Response

200 OK: Authenticator is updated.

{
  "authenticatorId": "f3ef70fc-9231-48f8-8e81-8eef7826d594",
  "name": "Personal Phone",
  "type": "ios",
  "enrolledAt": "2020-10-09T08:44:36Z",
  "updatedAt": "2020-10-09T08:44:36Z",
}

404 Not found: No authenticator with provided authenticatorId exists.

For the details of the response, see Authenticator.

Delete an authenticator

Delete an authenticator

# Set $authenticator_id
curl "https://$instance.mauth.nevis.cloud/api/v1/authenticators/$authenticator_id" \
  -X DELETE \
  -H "Authorization: Bearer $access_key"

authenticator_id = 'f3ef70fc-9231-48f8-8e81-8eef7826d594'
resp = requests.delete(f'https://{instance}.mauth.nevis.cloud/api/v1/authenticators/{authenticator_id}',
                       headers = {'authorization': f'Bearer {access_key}'})
print(resp.status_code) # => 204

An authenticator is deleted by its unique, permanent authenticatorId. After deleting an authenticator, the user can no longer use this authenticator for authentication.

HTTP Request

DELETE https://{instance}.mauth.nevis.cloud/api/v1/authenticators/{authenticatorId}

Parameters

HTTP Response

204 No Content: Authenticator is successfully deleted.

404 Not found: No authenticator with provided authenticatorId exists.

No response body is returned in case of successful deletion.

Integrating the Widget

The Authentication Widget enables Auth Cloud customers to integrate authentication capabilities into their existing infrastructure. The Widget can be embedded into a webapp in a matter of hours.

In order to prevent exposing your access key, the Authentication Widget uses temporary, one-time tokens that are tied to specific users and specific intent. Your backend needs to request these intent tokens from the Auth Cloud, using the access key, username or userId and the intent (enroll or approve). The widget, using the intent token returned by the Auth Cloud API, can then complete the transaction.

A generic flow may be as follows:

1. Your web app asks the user for a username and whether they want to register or log in.
2. The app sends this information bundle to your backend application.
3. Your backend, using the securely stored access key, calls the intent API endpoint to request a token for this user for this purpose.
4. The Auth Cloud API returns an Intent Token to your backend.
5. Your web app creates a widget config that contains:
   • Intent token
   • Result callback function
   • brand color
   • brand logo URI
6. Your web app instantiates the widget with the config and intent token.
7. The widget takes over control and instructs the user to install the app, authenticate with the phone and complete the action.
8. The widget relinquishes control and calls the result callback function with the result of the operation, for example success, and a data member with the userId, or error and a brief description.
9. For security purposes, the widget also returns a token with the result. Your frontend should send this to you backend.
10. Your backend doublechecks against the Auth cloud API if the token is valid. (See Checking Token Validity)
11. If it is valid, your backend completes the transaction for your user.

Request an intent token

When requesting an intent token, you need to specify the user for whom the token is issued and the purpose of the transaction, the intent, that will be carried out. Registration for new users is enroll, transaction signing for existing users is approve.

Requesting an intent token:

curl "https://$instance.mauth.nevis.cloud/api/v1/intent" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{ "username": "u12345", "operation": "enroll" }'

Requesting an intent token with channels:

curl "https://$instance.mauth.nevis.cloud/api/v1/intent" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{ "username": "u12345", "operation": "approve", "channels": ["push","sms"] }'

HTTP Request

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

Parameters

HTTP Response

200 OK

{
  "token":"eyJhb...ZgP_8NBw"
}