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

Patching¶

Card owners¶

Path	Allowed operations	Description
/FAMILYNAME	REPLACE	Change family Name
/SPECIFICNAME	REPLACE	Change specific Name
/PINCODE	REPLACE	Change pin code
/ORGANIZATIONID	REPLACE	Change organization
/FOLDERID	REPLACE	Change organizer folder
/COMMENT	REPLACE	Change comment
/STARTTIME	REPLACE	Change start time validity
/STOPTIME	REPLACE	Change stop time validity
/DISABLED	REPLACE	Change disabled state. Disable the card owner by setting this to true and Enable him by setting it to false

Grants¶

Path	Allowed operations	Description
/DISABLED	REPLACE	Change disabled state
/STARTTIME	REPLACE	Change start time
/STOPTIME	REPLACE	Change stop time

Cards¶

Path	Allowed operations	Description
/NAME	REPLACE	Rename card
/CLASSIFICATION	REPLACE	Change card classification
/PINCODE	REPLACE	Change pin code
/STARTTIME	REPLACE	Change start time validity of Card Owner
/STOPTIME	REPLACE	Change stop time validity of Card Owner
/DISABLED	REPLACE	Change disabled state of Card Owner

Folders¶

Path	Allowed operations	Description
/NAME	REPLACE	Rename organizer folder
/PARENTFOLDERID	REPLACE	Change parent folder
/DESCRIPTION	REPLACE	Change description

Organizations¶

Path	Allowed operations	Description
/NAME	REPLACE	Rename organization
/FOLDERID	REPLACE	Change organizer folder
/COMMENT	REPLACE	Change comment

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.

Pagination¶

Some operations have pagination support and all these operations can handle two query parameters for pagination:

Parameter	Datatype	Default	Description
offset	int	0	Offset from which the response will be filtered.
limit	int	50	Maximum number of items to return in request.

Example usage:¶

This will get a list of resources starting with offset 100 and limiting the response to the next 25 resources.

curl 'https://<api-endpoint>/resources?offset=100&limit=25'

Paging information in response¶

All operations supporting paging will include paging information in the response.

Parameter	Datatype	Description
totalCount	int	Number of items in total found.
offset	int	The offset used when handling the request.
limit	int	The number of items used when handling the request.

If the totalCount says -1 the API doesn’t know the total amount of items. If totalCount says 0 it means that no items were found (hence result should be empty).

Example pagination part in response:¶

{
  "apiVersion": "1.0",
  "correlationId": "7d0e6cac-d7da-4980-96c8-92c7a106ec88",
  "statusCode": 200,
  "message": null,
  "paging": {
    "totalCount": -1,
    "offset": 100,
    "limit": 25
  },
  "data": { ... }

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.
`X-Dax-CertificateThumbprint`	Thumbprint of the verified certificate.
`X-Dax-CertificateExpiresAtUtc`	Expiration date of the certificate.