In this section you will learn how you can use the REST API to automate various tasks such as user registration or transaction authentication.

To see all available REST API endpoints, see the REST API reference.

Prerequisites

Before you start experimenting with the API, make sure you have successfully completed the following tasks. 

If so, you now have the following:

  • Access Key
  • Mobile app installed and configured
  • Access to the management console

You will also need:

  • A bash prompt in a terminal (Linux, MacOS, or on Windows, Git bash or Powershell bash usually work fine).

Preparing Your Environment

You will need to prepare a few local variables in your shell so that the following scenarios can be run conveniently.

Copying the REST API Endpoint

  1. To copy the REST API endpoint for your Auth Cloud Instance, click Overview from the menu.
  2. Under your instance name, click the copy icon for Your REST API endpoint
  1. In your shell, type python --version. We expect to see that Python 3 is installed.
  2. Assign your NEVIS Access key (Bearer TOKEN) to a shell variable.

    export ACCESS_KEY=eyJhbGciOiJIUzUxMiJ9.eyJhdWQiOiJhcGkiLCJpc3Mi...rfeAsv2Yv4AfXG_ncfs7Bczdc3DO8zQGvC0g
    BASH
  3. Assign your REST API end-point to a shell variable. Make sure you include the trailing slash.

    export APIBASE=https://sandbox-int-6c1fcf.mauth.nevis.cloud/
    BASH

Registering your NEVIS Access app through the REST API using a QR Code

In this section, we send simple curl commands to the NEVIS REST API to:

  • Register your mobile device for authentication and then to

  • Query for your user account, using your email address.

We send your bearer token and your user name to the API. From the response, we decode the QR code in your browser, then use the NEVIS Access app on your mobile to read the code. Finally authenticate using biometric methods on your phones to complete the registration.

Registering your mobile phone

  1. To enroll your device, send your bearer token and user name to the API with the following command. Replace the username with your email.

    curl -XPOST \
      -H "Authorization: Bearer $ACCESS_KEY" \
      -H 'Content-Type: application/json' \
      -d '{"username":"[email protected]"}' \
      ${APIBASE}api/v1/users/enroll | python -m json.tool
    BASH

    The response contains a Base64 encoded QR code that can be read by the NEVIS Access app on your mobile phone.

    {
        "userId": "11ff2eb5-7def-4e8f-9eb2-e82bdfbf2b4d",
        "username": "[email protected]",
        "status": "new",
        "createdAt": "2020-06-30T08:47:59.168663Z",
        "authenticators": [],
        "enrollment": {
            "transactionId": "56bd1216-d971-436e-a599-bd02a31c44f0",
            "statusToken": "eyJhbGciOiJIUzUxMiJ9.eyJhdWQiOiJzdGF0dXMiLCJpc3MiOiJodHRwczovL3NhbmRib3gtaW50LTZjMWZjZi5tYXV0aC5uZXZpcy5jbG91ZC8iLCJpYXQiOjE1OTM1MDY4NzksImp0aSI6IjU2YmQxMjE2LWQ5NzEtNDM2ZS1hNTk5LWJkMDJhMzFjNDRmMCIsInN1YiI6IjExZmYyZWI1LTdkZWYtNGU4Zi05ZWIyLWU4MmJkZmJmMmI0ZCJ9.iCiBKB59ObaDV7QCNGF6avdh-2rO6njX0eSq5Ky0FOaN1tqSMXyjae27BtVmd3AgvG8zFxQ12vs8D3suCjJGLg",
            "qrCode": {
                "type": "image/png",
                "size": 300,
                "dataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADo0lEQVR4Xu3XbZLVIBCFYXbA/nfJDrCfw9VkUk7pH+0pvZQ3Ic2L1d8wY//OWOMp+el4Y4/xxh7jjT3Gv4KtMUZN6jnnWjOvufZae1jqxepfTfxmLSxrxa9RX1ntxCyV1juqB5xlUVlgyxfAANNvF73rWQYQfwFsE9Vq+VUelGDGrnYMKSElYn2Vc6ccGD4eGfLXMSXzyXhW1ifjj2EZ0XdGUsaIfuUp9Y0+TEbuhLrcyqAJh5FelrZgQ5WsvItcp3JUTbndlkaM9ukzHKuASrjsrDqa6rsRS8kex1KbATNHxyS/ubcDIzo1HMcKfsjpmLtVfQ+m/UX10tiL/vXbSYpOLFHXlKcEcOAGe+0GdGJba9akp0xMtyaK9GZCA6YTuwPkHqBucqBZWkS9mAAvGeAuldxMEzQHdmLl3+8Hroj74OGhDcrTVsx0an9Urkl6oOy02WjEnBqnSasYpiht9qTUm7Gdhrf0mLQYheJX5FVZLVgSUrkshmSfHSpG++nEKtLbN3eiwsS7EvV2fDRgW6mME3oVfQonObr0n2ZsuzQJtDJep+Ew62PVN2A6SzqN0skkVnD1I/QtGHdaqQW/WtV/UtrN2HTBk5bglUtxTrWZv4VaMVeVxauuopmg6K4hAvqwKB6dc96mYhixY9DNvQ2YJqgFWk64TabKYVr+ozZMsAXZtW4k3EmEI34RfZgoU5Zfhb5E0nGqZzb2YYk6rc8Jl6KuHJCbnq3YojRdpwbDsRaFviTzcm8LJgu3jjwJcqDFGrnwIrqwaDuULkvUsy/v6j6XCT3Y1Js5dqd69R1XZbbJiVZMHqqT9BbHiHmJ4nOPRix6gtKqq7tohcpGgl4mtGDOMVYMDecQJdF8XExbsSgcV0ZnuwhCx4JGbL96y6BzNslRW1TQzb0NmMqN+lSWAsKffnNOkU4sJpRsyceXkAH1U0G9mHcQBy9Hh6qP02g6sZVwp8U427j0XKKEPv7tw7ZKznmrV599BMW4TPViqRS1wQIZUJ2HHVL03i07sKNpvDqcGpnIVGb1YjJS1PkTZwP8wFeG9GD1rbe8piE16or+aMaMl+4iHwtkp3JORjRiIq9sZnr10v3GaYy16SqZHowFHnw5RX5F5vNuQgtG1andUF64E3qZ6Shuxzwkpg0lJV85dz+a0IPVZPCtv35mGOVcrx/Hbg+G5Mmab+WbnIRlQy82IJM3V3Jgnpo50OXeDuzX4409xht7jDf2GP8R9g3b8qzbIiNhswAAAABJRU5ErkJggg"
            },
            "appLinkUri": "https://sandbox-int-6c1fcf-app.mauth.nevis.cloud/open?dispatchTokenResponse=eyJubWFfZGF0YSI6eyJ0b2tlbiI6IjY5YTEwYWQ4LTc2ZjQtNDU1NC05OTkyLTE0YWNiYmE4YzBiYiIsInJlZGVlbV91cmwiOiJodHRwczovL3NhbmRib3gtaW50LTZjMWZjZi5tYXV0aC5uZXZpcy5jbG91ZC9fYXBwL3Rva2VuL3JlZGVlbS9yZWdpc3RyYXRpb24ifSwibm1hX2RhdGFfY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vanNvbiIsIm5tYV9kYXRhX3ZlcnNpb24iOiIxIn0"
        }
    }
    CODE
  2. Copy the contents of the dataUri without the double quotes, and paste it in your browser to display the QR code used by the NEVIS Access app.



Usernames for Production
In a production site, usernames need to be unique and permanent. For this reason email addresses should not be used as they can and will change during the user lifecycle. Ideally, a sufficiently memorable unique username would be used, accompanied by the user's current email address.

Registering with your Mobile App

Registering with your mobile phone
  1. On your mobile phone, open the NEVIS Access app.

  2. Tap the Read QR Code button.

  3. Scan the QR code of the dataUri you displayed in your browser in Step 2 above.

  4. Select a biometric method such as fingerprint or facial recognition .

  5. On the Registration Successful page, tap Close.

Testing if your registration was successful

You can look up your user with the following command:

curl -H "Authorization: Bearer $ACCESS_KEY" \
    ${APIBASE}api/v1/[email protected] \
    | python -m json.tool
BASH

The response contains the user records including the user ID, whether the account is active or not, and also the date of creation and the last update.

{
    "userId": "11ff2eb5-7def-4e8f-9eb2-e82bdfbf2b4d",
    "username": "[email protected]",
    "status": "active",
    "createdAt": "2020-06-30T08:34:54Z",
    "authenticators": [
        {
            "authenticatorId": "95ebe358-79b4-46d1-848a-117511503151",
            "name": "your iPhone",
            "type": "ios",
            "enrolledAt": "2020-06-30T09:22:29Z",
            "updatedAt": "2020-06-30T09:22:29Z"
        }
    ]
}
PY

Lookup by userId

Each user is assigned a unique, fixed user ID that can also be used for lookups. This never changes, unlike other user generated fields. Also note that the username can be any arbitrary string, such as an email, a hashed value or a Microsoft Azure UUID, while the user ID is permanent and uniform.

  1. Copy your userId from the response above.

  2. Replace the last element in the URL below with your userId and run a search with the following:

    curl -H "Authorization: Bearer $ACCESS_KEY" \
        ${APIBASE}api/v1/users/<ADD-YOUR-userId-HERE>  \
        | python -m json.tool
    BASH

    You expect to see a similar response like above.

Summary

In this short tutorial, we have demonstrated how to use your API key to register a user using the NEVIS REST API, and a mobile-first solution that is safer and faster than traditional password based methods.

Next steps

Get your own branded access app from NEVIS?

You can easily provide your users with the convenience and security of a FIDO certified authentication app with the NEVIS Authentication Cloud service. Your logo, your colors, your app in the app store with the security features of a Swiss bank under the hood.