API Authentication Mechanisms

What it is

API authentication is the way a client proves who it is before the server allows a request.

The three mechanisms on the outline are basic authentication, custom tokens and API keys. They differ in what the client sends and how long it lasts.

Authentication answers who you are. Authorisation answers what you may do. A 401 code points to the first, and a 403 code to the second.

How it works

Each mechanism puts a credential into the request, usually in a header.

Basic authentication

The client sends a username and password in the Authorization header. The header value is the word Basic followed by the text username:password encoded with Base64.

Authorization: Basic YWRtaW46cGFzc3dvcmQ=

Base64 is an encoding, not encryption. Anyone who sees the header can decode it. Basic authentication is therefore safe only over HTTPS.

In Python, requests builds the header for you.

import requests

response = requests.get(
    BASE_URL + "/v1/devices",
    auth=("admin", PASSWORD),
)

Custom token authentication

The client first logs in with its credentials and receives a token. It then sends the token with each later request, so the password is sent only once.

Cisco Catalyst Center works this way. A POST to /dna/system/api/v1/auth/token with basic authentication returns a token. The client sends it in the X-Auth-Token header on later calls.

auth_response = requests.post(
    BASE_URL + "/dna/system/api/v1/auth/token",
    auth=("admin", PASSWORD),
)
token = auth_response.json()["Token"]

headers = {"X-Auth-Token": token}
devices = requests.get(
    BASE_URL + "/dna/intent/api/v1/network-device",
    headers=headers,
)

A token has a limited life. When it expires, the API answers 401 and the client logs in again. The header name is chosen by each product, which is why this is called a custom token.

Bearer tokens

Many cloud services use the standard Authorization header with the word Bearer and then a token. This is typical for tokens issued after an OAuth login, such as Webex access tokens.

Authorization: Bearer ACCESS_TOKEN

The token itself is a long random string. Whoever holds it can use it, so it must be protected like a password.

API keys

An API key is a long string that identifies the calling application or account. The client sends it with every request, often in a header, and sometimes as a query parameter.

Cisco Meraki uses an API key. The key is generated in the dashboard by a user and sent in a header.

headers = {
    "X-Cisco-Meraki-API-Key": API_KEY,
    "Content-Type": "application/json",
}
response = requests.get(BASE_URL + "/organizations", headers=headers)

A key does not normally expire by itself. It lasts until someone revokes it, so a leaked key stays dangerous.

Comparing the mechanisms

Keeping credentials safe

• Always use HTTPS, so that headers cannot be read on the network.
• Never write secrets into source code or commit them to Git.
• Read them from environment variables or a secrets manager.
• Give each token only the access it needs.
• Rotate or revoke a credential that may have leaked.

import os

API_KEY = os.environ["MERAKI_API_KEY"]