Accessing the API

To access the API, each request must have a proper Authorization header.

The Authorization header must be in the form:

Authorization: Bearer <AUTH TOKEN>

where <AUTH TOKEN> is a string obtained through the login API call, described below.

Please note that the < and the > signs should be removed and replaced with the token.

Login API

To obtain an auth token issue a call to the Login API which can be accessed from the URL path /v2/login and send a POST request containing a JSON object that includes the username and password fields with the correct values as the following example shows:

curl -XPOST 'https://api-pdns.deteque.com/v2/login?pretty' \
     -H 'Content-Type: application/json' -d'
{
  "username": "test",
  "password": "test"
}
'

In the case of success, the HTTP status code will be 201 and the body will contain a JSON object similar to the following one:

{
    "status": "ok",
    "token": "eyJ0eXAiOi...[CUT]...pVH3wEDSVM",
    "expires": 1544026975
}

In the case of error, the API will return a different status code (usually 401 or 422) and a different JSON object:

{
    "status":  "error",
    "message": "Not authorized",
    "error":   401
}

After successful login you must save the auth token to further access the API. The successful JSON response object will include an “expires” integer field that represents the UTC timestamp the token expires. The token must be renewed prior to expiration to avoid interruptions in service.

When an auth token has expired any subsequent API requests will result in a 401 Unauthorized HTTP response code. In this case a new auth token is needed before sending additional API requests.

NOTE: Please do NOT request an auth token for each API request. To protect against brute force attacks this behavior is penalized and may result in API access being temporarily blocked.