Authentication

The Heron API uses API Keys to authenticate requests. 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>

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

If authentication fails, the API will return a 401 Unauthorized status code:

{
  "error": {
    "code": "authentication_failed",
    "message": "The provided API key is invalid or has expired."
  }
}