Authentication

The Heron API supports two customer authentication modes:

• API keys in the X-API-Key header
• user bearer tokens in the Authorization header

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

API Keys

API keys are the simplest way to authenticate with Heron. They are standard strings that you include in the X-API-Key header of your requests.

Header Format

X-API-Key: <your_api_key>

Bearer Tokens

User-scoped requests can also authenticate with a bearer token:

Authorization: Bearer <your_jwt>

Bearer tokens represent a signed-in Heron user rather than a service credential. Use them when an endpoint acts on the current user context.

Bearer-Only Endpoints

Most public API endpoints accept either authentication mode, but some endpoints require a user bearer token specifically.

For example, GET /v1/users/me only accepts Authorization: Bearer <jwt>. Calling that endpoint with an API key returns 403 Forbidden with the user_token_required error code.

Security Best Practices

• Never share your API keys: If a key is compromised, revoke it immediately in the dashboard.
• Use environment variables: Store keys in your server's environment variables rather than hardcoding them in your source code.
• Rotate keys regularly: We recommend rotating your keys every 90 days as part of your security policy.

Error Responses

Authentication errors use the standard API error payload directly. There is no outer error wrapper object.

If you omit credentials entirely, the API returns 401 Unauthorized:

{
  "code": "missing_credentials",
  "message": "Missing credentials"
}

If you send an invalid API key or bearer token, the API returns 401 Unauthorized:

{
  "code": "unauthorized",
  "message": "Unauthorized"
}

If you call a bearer-only endpoint with an API key, the API returns 403 Forbidden:

{
  "code": "user_token_required",
  "message": "This endpoint only accepts a user token (Bearer JWT)."
}

If Heron's auth infrastructure is temporarily unavailable, the API returns 500 Internal Server Error:

{
  "code": "auth_failure",
  "message": "Authentication service unavailable"
}