DAX REST API

This API makes it possible to handle entities such as but not limited to card owners, cards and grants. To be able to use this API a contract between partners is needed.

Authentication

Authentication is the Oauth 2 scheme with username, password, client id and password flow grant type.

A token can be requested by issuing a POST request to the token endpoint located at https://api-prod.dax.amido.io/oauth/token with the OAuth 2 parameters either as form body (recommended) or as a query string.

username=<USERNAME>&password=<PASSWORD>&client_id=<INSTANCE ID>&grant_type=password

In the response your token and it’s validity will be presented as a json response.

{
  "access_token": "eyJhb.....",
  "token_type": "bearer",
  "expires_in": 900
}

The access_token must be presented in an authorization request header for all subsequent requests.

Authorization: Bearer eyJhb......

HTTP Request signing

If using the V2 versions of the API (recommended) you need to create a private/public key pair and provide Amido with your public key before you can consume the API. The instructions for the actual calls can be found here: Signing of HTTP Messages.

Schema

All API access is over HTTPS and accessed from https://api-prod.dax.amido.io/. All data is sent and received as JSON.

All timestamps are returned in ISO 8601 format and the internal timestamps in DAX is UTC based whereas Alliera timestamps will be local time of Alliera instance.

YYYY-MM-DDTHH:MM:SSZ

Versioning

New version of the API may be published any time. In order to target a version all API endpoints have a version part. Available versions will be presented in the response header api-supported-versions.

Current version is 2.0 and it’s endpoint is https://api-prod.dax.amido.io/v2.0/ and requires signed HTTP Requests.

HTTP Redirects

DAX WebAPI might use HTTP redirection when deemed appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow the redirect.

Status Code Description
301 Moved Permanently. This and all future requests should be directed to the given URI.
302, 307 Temporary redirection. In this case, the request should be repeated with another URI;
however, future requests should still use the original URI. In contrast to how 302 was
historically implemented, the request method is not allowed to be changed when
reissuing the original request. For example, a POST request should be repeated
using another POST request.

Redirection status code not listed above may be used but will adhere to the HTTP 1.1 specification.

Context

With each request it’s possible to add a request context. The request context will be part of the response headers; the value will just copied and returned. The purpose of the request context is to make it easier for decoupled systems to pair a request with its response.

The context can be set to anything but is limited to 255 characters.

The Context parameter must be passed in the body of the request even if it’s a GET request.

{
  "Context": "Requesting context"
}

Rate limiting

For API requests using OAuth the number of requests you can make is limited. Your current limitation is presented in the API responses.

X-Rate-Limit-Limit: 7d
X-Rate-Limit-Remaining: 9998
X-Rate-Limit-Reset: 2020-03-04T07:46:24.6607163Z

See response headers below for more information.

Request headers

Header Description
Content-Type The Content-Type for all requests must be set to application/json.
Failure to do so will result in a 400 Bad Request error.

Response headers

Header Description
X-Dax-Context Mirror of the context parameter available in all requests.
X-Dax-Response-Time-ms Response time for the internal processing of the request.
X-Correlation-Id A GUID that is unique to all processing done by this request.
In order for Amido to debug any problems this Id is crucial.
X-Rate-Limit-Reset UTC timestamp for when the next reset of rate limitation window will be
made.
X-Rate-Limit-Remaining The number of requests still available in the current limitation window.
X-Rate-Limit-Limit The limitation window for which the current rate limitations apply.
api-supported-versions The available REST API versions available.