KeyAuth - engineering

KeyAuth authenticates requests using Unkey API keys. It is the only authentication policy the engine executes today; JWTAuth is defined in the schema but not yet active.

Fields

key_space_ids

string[]

List of keyspace IDs the key must belong to. If the key belongs to a keyspace not in this list, authentication fails with Frontline.Auth.InvalidKey.

locations

KeyLocation[]

Ordered list of locations to extract the API key from. Frontline tries each location in order and uses the first non-empty key. If omitted, defaults to extracting a Bearer token from the Authorization header.

permission_query

string

Optional RBAC query evaluated against the key’s permissions. If the key does not satisfy the query, authentication fails with Frontline.Auth.InsufficientPermissions.

Examples

Bearer token (default)
Custom header
Header with prefix stripping
Query parameter
With permissions

{
  "policies": [
    {
      "id": "api-auth",
      "name": "Authenticate API keys",
      "enabled": true,
      "match": [],
      "keyauth": {
        "key_space_ids": ["ks_abc123"],
        "locations": [
          { "bearer": {} }
        ]
      }
    }
  ]
}

{
  "policies": [
    {
      "id": "api-auth",
      "name": "Authenticate via X-API-Key header",
      "enabled": true,
      "match": [],
      "keyauth": {
        "key_space_ids": ["ks_abc123"],
        "locations": [
          { "header": { "name": "X-API-Key" } }
        ]
      }
    }
  ]
}

{
  "policies": [
    {
      "id": "api-auth",
      "name": "Authenticate with prefix stripping",
      "enabled": true,
      "match": [],
      "keyauth": {
        "key_space_ids": ["ks_abc123"],
        "locations": [
          { "header": { "name": "Authorization", "strip_prefix": "ApiKey " } }
        ]
      }
    }
  ]
}

Placing API keys in query parameters is dangerous and should only be used as a last resort for trusted-internal services. Query strings are logged by proxies, CDNs, and web servers, cached by browsers and intermediaries, saved in browser history, and leaked to third parties via the Referer header. Prefer the Authorization header (bearer or header location) whenever possible.

{
  "policies": [
    {
      "id": "api-auth",
      "name": "Authenticate via query param",
      "enabled": true,
      "match": [],
      "keyauth": {
        "key_space_ids": ["ks_abc123"],
        "locations": [
          { "query_param": { "name": "api_key" } }
        ]
      }
    }
  ]
}

{
  "policies": [
    {
      "id": "api-auth",
      "name": "Authenticate with RBAC",
      "enabled": true,
      "match": [],
      "keyauth": {
        "key_space_ids": ["ks_abc123"],
        "locations": [{ "bearer": {} }],
        "permission_query": "(api.keys.read OR api.keys.list) AND billing.read"
      }
    }
  ]
}

Key extraction

Frontline supports three key extraction locations:

Location	Behavior
Bearer	Reads the `Authorization` header and strips the `Bearer` prefix (case-insensitive)
Header	Reads a named header. Optionally strips a prefix (case-insensitive)
Query parameter	Reads a named query parameter. Security risk: query strings are recorded in server logs, proxy logs, CDN logs, browser history, and `Referer` headers. Use only as a last resort for trusted-internal traffic; prefer `bearer` or `header` locations.

When multiple locations are configured, Frontline tries each in order and uses the first non-empty result.

Verification flow

Extract the key from the request using configured locations.
Hash the key using SHA-256.
Look up the hash in the key cache (fresh: 10s, stale: 10min, max: 100k entries).
Validate key status. Keys that are not found, disabled, expired, or belong to a disabled workspace are rejected.
Verify the key belongs to one of the configured key_space_ids.
Parse the permission query (if configured) and build verify options.
Call verifier.Verify() with 1 credit deduction per request.
Write rate limit headers (regardless of success or failure).
Check post-verification status (rate limit, usage exceeded, permissions).
Build and return the principal on success.

Response headers

KeyAuth writes rate limit headers on every response, including rejected requests:

Header	Value
`X-RateLimit-Limit`	Rate limit ceiling
`X-RateLimit-Remaining`	Remaining requests in the window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds until retry (only on 429 responses, minimum 1 second)

Error responses

Scenario	Status	Code
No key found in request	401	`Frontline.Auth.MissingCredentials`
Key not found in database	401	`Frontline.Auth.InvalidKey`
Key disabled	401	`Frontline.Auth.InvalidKey`
Key expired	401	`Frontline.Auth.InvalidKey`
Key not in allowed keyspace	401	`Frontline.Auth.InvalidKey`
Workspace disabled	401	`Frontline.Auth.InvalidKey`
Permission query not satisfied	403	`Frontline.Auth.InsufficientPermissions`
Rate limit exceeded	429	`Frontline.Auth.RateLimited`
Usage limit exceeded	429	`Frontline.Auth.RateLimited`
Invalid permission query syntax	500	`Frontline.Internal.InvalidConfiguration`

​Fields

​Examples

​Key extraction

​Verification flow

​Response headers

​Error responses

Fields

Examples

Key extraction

Verification flow

Response headers

Error responses