API authentication methods explained

Most APIs authenticate one of a handful of ways. Here's what each sends on the wire, and where you'll actually run into it.

Bearer token

A token sent in the Authorization header, prefixed with Bearer:

Authorization: Bearer eyJhbGciOi...

The most common scheme for APIs that issue their own tokens — session tokens, JWTs, or a personal access token you generated once. The server validates the token; anyone holding it can act as whoever it belongs to, so it should only ever travel over HTTPS.

Basic auth

A username and password, joined with a colon and base64-encoded:

Authorization: Basic dXNlcjpwYXNzd29yZA==

Base64 is encoding, not encryption — Basic auth is only as safe as the HTTPS connection carrying it. It's common on internal tools and simple services, less common on public APIs.

API key

A static string identifying the caller, sent either as a header or a query parameter, depending on the API:

X-API-Key: sk_live_abc123
# or
GET /v1/data?api_key=sk_live_abc123

Simple to issue and revoke, which is why it's common for third-party/public APIs. A key in a query string ends up in server logs and browser history more easily than one in a header, so prefer the header form when the API supports both.

OAuth 2.0

A framework for getting a token rather than a single header format. The client-credentials grant — the common case for service-to-service calls with no end user involved — exchanges a client id and secret for an access token at a token endpoint, then uses that token as a bearer token on subsequent requests:

POST /oauth/token
grant_type=client_credentials&client_id=...&client_secret=...

-> { "access_token": "...", "expires_in": 3600 }

Other grants (authorization code, password, implicit) exist for flows that do involve an end user signing in, which is a different problem than authenticating a single API call.

Setting these up once instead of per-request

Whichever scheme an API uses, you want to configure it once and have it apply consistently — see Voyager's authentication editor, which currently supports bearer, Basic, API key, and OAuth 2.0 client-credentials.