Provider gateway

Send a Gate Token as a bearer credential. A browser session, MCP session token, public token identifier, or raw provider key is not valid gateway authentication.

Authorization: Bearer gk_test_<public_id>_<secret>

The gateway chooses an OpenAI-compatible provider in this order:

1. An explicit X-Gatekyper-Provider header.
2. A provider prefix in the model, such as openrouter:vendor/model. The prefix is removed before forwarding.
3. The one OpenAI-compatible provider allowed by the attached policy, if unambiguous.
4. OpenAI as the final default.

Optional headers add task and tracing context to the usage or denial event and can be required by policy:

X-Gatekyper-Task

Recorded as task_id.

X-Gatekyper-Trace-Id

Recorded as trace_id for correlation with another system.

X-Gatekyper-App

Recorded as app metadata supplied by the caller.

X-Gatekyper-Agent

Recorded as agent metadata supplied by the caller.

Authoritative project, application, actor, and environment identity comes from the Gate Token record. Caller-supplied metadata does not replace that ownership boundary.

Most OpenAI-compatible clients need only a base URL override and the Gate Token in the usual API-key setting.

OPENAI_BASE_URL=http://127.0.0.1:4100/v1
OPENAI_API_KEY=gk_test_example_replace_with_display_once_token

The value above is synthetic. Replace it at runtime; do not commit the issued token.

curl --fail-with-body http://127.0.0.1:4100/v1/chat/completions \
  -H "Authorization: Bearer ${GATEKYPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Gatekyper-Provider: openai" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 32
  }'

Anthropic uses its native Messages request and response format behind the provider-prefixed path. Gatekyper injects the stored x-api-key and version header upstream.

curl --fail-with-body http://127.0.0.1:4100/proxy/anthropic/v1/messages \
  -H "Authorization: Bearer ${GATEKYPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

X-Gatekyper-Request-Id

A safe identifier for usage, denial, support, and trace correlation.

X-Gatekyper-Policy-Decision

allowed, observe_only, or denied.

X-Gatekyper-Estimated-Cost-Usd

The preflight estimate used for reservation on an allowed response; not a final provider invoice.

X-Gatekyper-Denial-Reason

A safe machine-readable reason on denials where one is available.

The gateway preserves the upstream status for forwarded responses except that provider authentication failures are replaced with a safe Gatekyper error so raw provider error content cannot leak sensitive detail.

Server-sent event streams pass through without waiting for completion. A monitor branch observes the stream for usage extraction and finalizes the event after completion or disconnect.

When usage cannot be extracted—because of a disconnect, oversized capture, or provider shape—the budget settles to the conservative preflight estimate so a hard-stop window is not under-counted.

{
  "error": {
    "code": "gatekyper_policy_denied",
    "reason": "model_not_allowed",
    "message": "This token is not allowed to use the requested model.",
    "request_id": "gk_req_example"
  }
}

401

Missing, invalid, revoked, or expired Gate Token.

403

Policy or route denial.

429

Budget or rate limit exceeded.

502

Provider authentication failure or unreachable upstream.

503

Provider route disabled or no usable configured provider route.

500

The gateway could not safely evaluate an internal dependency and failed closed.

Branch client behavior on error.code and error.reason, retain the request identifier, and avoid parsing the human message.