Authenticating with the API

Almost every request to the API must supply authentication credentials. Failing to do so returns a 401 Unauthorized response with a payload like this:

{
  "data": { "message": "invalid credentials" },
  "error": "401",
  "message": "invalid_credentials",
  "status": "error",
  "timestamp": "{TIMESTAMP}",
  "version": "{VERSION}",
  "node": "{API_NODE}",
  "request_id": "{REQUEST_ID}",
  "auth_token": "{AUTH_TOKEN}"
}

The API provides several ways to authenticate a request. The most common is to authenticate as a user and receive a token you use on subsequent requests.

Basic authentication

A simple and quick method. Add an Authorization HTTP header to the request, with method Basic and a value made up of your account ID concatenated with the MD5 hash of the username and password.

Token-based authentication

This is the preferred and more secure approach. You log in once to get a token, then set that token in the X-Auth-Token header on subsequent requests. There are two ways to log in.

Authenticate as a user

The best way to get a token for UI applications and manual requests. You provide your user credentials for login only, and the API returns an authentication token.

The credentials value is the MD5 hash of USERNAME:PASSWORD. For a username of john@example.com and a password of m32c6NfqYEt, the hash of john@example.com:m32c6NfqYEt — note the colon separating the two — is 82a2dc91686ec828a67152d45a5c5ef7.

To generate the hash in a terminal, use md5sum on Linux or md5 on macOS:

echo -n 'john@example.com:m32c6NfqYEt' | md5sum
# 82a2dc91686ec828a67152d45a5c5ef7  -

You can also use the more secure SHA1 as your hash function — generate it with shasum. If you are using a programming language, refer to its documentation on generating the hash.

You also need one more field to identify the user: the account’s name, the account’s realm, or a phone number assigned to this user.

With that ready, call the user_auth API to get a token:

curl -v -X PUT \
  -H "Content-Type: application/json" \
  -d '{"data":{"credentials":"82a2dc91686ec828a67152d45a5c5ef7", "account_name":"{ACCOUNT_NAME}"}, "method":"md5"}' \
  'https://{SERVER}:8443/v2/user_auth'

A successful response:

{
  "auth_token": "{AUTH_TOKEN}",
  "data": {
    "account_id": "{ACCOUNT_ID}",
    "apps": [],
    "is_reseller": true,
    "language": "en-US",
    "owner_id": "{OWNER_ID}",
    "reseller_id": "{RESELLER_ID}"
  },
  "node": "{API_NODE}",
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success",
  "timestamp": "{TIMESTAMP}",
  "version": "{VERSION}"
}

{AUTH_TOKEN} is a long string you use on future requests:

curl -X GET \
  -H "X-Auth-Token: {AUTH_TOKEN}" \
  'https://{SERVER}:8443/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}'

Account API authentication

Uses your account’s API key to generate an authentication token. If you are building a server application, this is the best way to authenticate it. It works the same as authenticating as a user, except you supply the API key as the data:

curl -X PUT \
  -d '{"data": {"api_key":"{API_KEY}"} }' \
  'https://{SERVER}:8443/v2/api_auth'

You can find the API key in the Authentication application in the UI, or retrieve it through the Accounts API.