Developer documentation overview

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, such as SMS or recovery codes.

caution

This API is designed to be only used for server-to-server calls. Never expose your access keys on the client side or in untrusted contexts, such as browsers or mobile apps.

When you sign up for the service, use the Management Console to obtain the API endpoint URL and generate an access key for the machine-to-machine communication with your Nevis Authentication Cloud.

cURL example

# 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

Python 3 example

# 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 = ...

Variables in cURL code samples

In our documentation, we use variables in the cURL samples. Make sure that the variables are defined before you use the samples. Variables are marked with $, for example, $username.

API basics

Endpoint

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

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

cURL example

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

Python 3 example

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

note

Replace {instance} with your instance ID. You can find your full API endpoint base URL in the Management Console.

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. The access key must be included in each API request to the server in a header as follows:

Authorization: Bearer {access_key}

note

Replace {access_key} with your access key.

API calls have the following rules:

• 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.

caution

Keep your access keys secure because they carry many privileges. Do not share your secret access keys in publicly accessible areas, such as GitHub or client-side code.

Intent tokens

An intent token is a one-time token that expires quickly, and it 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 Intent endpoint 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

The Authentication Cloud API accepts JSON-encoded request bodies and returns JSON-encoded responses. It also uses standard HTTP response codes, authentication, and verbs. If an endpoint expects a different content type, then this difference is noted in the documentation.

Versioning

We release backwards-compatible new versions of the API. The API version is noted in the URL. You can expect the same version to return the same information over time. New features are added either as new fields, options, or exposed as different resources.

API endpoint:

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

Current API scheme: v1

Errors

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

The following error codes can be returned:

• 400 Bad Request: Indicates that the sent request is malformed, for example, the request has wrong headers or invalid JSON formatting.

  Example

  400 Bad Request: Request body was not 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",
  }

• 401 Unauthorized: Indicates that the Authorization header is missing in the request.

• 403 Forbidden: Indicates that the access key provided for the call is not valid.

  Example

  403 Forbidden: Invalid access key provided

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

• 404 Not Found: Indicates that the specified resource is not found, for example, the user with the provided user ID does not exist.

• 405 Method Not Allowed: Indicates that the API endpoint does not exist.

• 409 Conflict: Indicates that a duplicate piece if content is detected, usually in creation API calls.

• 412 Precondition Failed: Indicates a failed operation in status polling.

• 415 Unsupported Media Type: Indicates that the provided media is invalid, for example, sending a form encoded POST request body instead of JSON.

• 5xx: Any 5xx error code indicates a server-side problem. We recommend contacting Nevis support if these errors occur.