Core concepts

Authenticate API requests

Relayline uses bearer API keys. Include one key in the Authorization header of every request.

Send an API key

Pass the key after the Bearer scheme. Store it in an environment variable instead of writing it directly into application code.

Authenticated requestcurl
curl https://api.relayline.example/v1/deliveries/dlv_01J6Y3G8V9K2M4P7Q1R5 \
  --header "Authorization: Bearer $RELAYLINE_API_KEY"

Use the correct environment

Test and live keys are isolated. A resource created with a test key cannot be retrieved with a live key.

EnvironmentKey prefixUse it for
Testrl_test_Development, automated tests, and staging
Liverl_live_Production deliveries to real destinations

Protect your keys

  • Keep keys in a secrets manager or encrypted environment configuration.
  • Create separate keys for each application and environment.
  • Rotate a key immediately if it appears in logs, source control, or client-side code.
  • Delete keys that are no longer attached to an active workload.

Rotate a key without downtime

Keep the existing key active while you deploy its replacement. Revoke the old key only after every workload has switched successfully.

  1. Create a replacement key in the same environment.
  2. Store the new value in your secrets manager and deploy it to each workload.
  3. Confirm successful requests from every workload.
  4. Revoke the old key and monitor for 401 responses.

Resolve authentication errors

A missing, malformed, revoked, or environment-mismatched key returns 401 Unauthorized.

Response · 401 Unauthorizedjson
{
  "error": {
    "code": "authentication_failed",
    "message": "The API key is missing or invalid.",
    "request_id": "req_01J6Y44C9N7Q2H5K8M3P"
  }
}

Check that the header begins with Bearer, the environment variable is available to the running process, and the key belongs to the environment you are querying. Record the Relayline-Request-Id response header if you need support.