API authentication & required headers

Overview

This article explains how to authenticate to the API, which headers are required on every request, and the most common causes of 401/403 errors. It also includes examples you can copy into Postman or curl.

Supported authentication (what to use)

Your account will be configured for one of the following methods (your onboarding pack will confirm which one applies):

Option A: API key (static token)

You send a single API key on every request.
Best for server-to-server integrations with limited rotation needs.

Option B: OAuth 2.0 (bearer token)

You obtain an access token, then send it on every request.
Best for more granular access control and easier rotation.

Required headers (every request)

Include these headers on all API calls:

Authorization:
- API key: Authorization: ApiKey <your_api_key>
- OAuth: Authorization: Bearer <access_token>
Content-Type: application/json (for requests with a JSON body)
Accept: application/json
User-Agent: <your-app-name>/<version> (recommended for tracing)

Optional but recommended headers

Idempotency-Key: <unique-value> for safely retrying POST requests
X-Correlation-Id: <uuid> to help trace requests end-to-end

Note: Some endpoints may require additional headers (for example, partner identifiers). Those will be documented per endpoint.

Sandbox vs production: common mismatch

Many 401 issues are caused by mixing environments:

Sandbox base URL + production credentials (or vice-versa)
Tokens generated for one environment used against the other

Always verify:

You’re calling the correct base URL for the environment
The credentials/token were issued for that same environment

Examples

Example 1 — curl with OAuth bearer token

bash

curl -X GET "https://{base-url}/v1/health" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json" \
  -H "User-Agent: aqua-integration/1.0"

Example 2 — curl with API key

bash

curl -X GET "https://{base-url}/v1/health" \
  -H "Authorization: ApiKey {api_key}" \
  -H "Accept: application/json" \
  -H "User-Agent: aqua-integration/1.0"

Example 3 — POST with JSON body + idempotency key

bash

curl -X POST "https://{base-url}/v1/bookings" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: 7b6d9f6a-2f10-4b21-8c2f-0a0f4f2d1a91" \
  -d '{"example":"payload"}'

Troubleshooting 401/403 quickly

Check these in order:

Environment match (base URL and credentials/token)
Authorization header format (prefix + spacing)
Token validity (expired token / clock drift)
Missing required headers (Accept, Content-Type where needed)
Proxy/gateway rewriting headers (ensure headers arrive unchanged)

What to include when contacting Support

To start diagnosis fast, include:

Environment (sandbox/production)
Endpoint + method + timestamp (with timezone)
Full request headers (secrets redacted)
Request/response bodies (secrets redacted)
HTTP status + error message
Any request/correlation IDs returned by the API
Steps to reproduce and frequency (always/intermittent)

FAQ

Do I need Content-Type on GET requests?
Not usually. Use it when you send a JSON body (POST/PUT/PATCH).

Can I retry POST requests safely?
Yes—use Idempotency-Key so retries don’t create duplicates.

Why do I see intermittent 401 errors?
Most often: token refresh timing, clock drift, or multiple services using different credentials.

Search