Skip to main content

​
Toolken headers

These headers are read and stripped by the gateway before the request is forwarded to the provider.

​
BYOK provider credential headers

These headers are forwarded verbatim to the upstream provider. The gateway does not validate or store them. Both headers can be present on the same request when the provider accepts dual auth. All headers not in the Toolken namespace are forwarded unchanged.

​
Claude Code attribution headers

When you route Claude Code through Toolken, Claude Code automatically sends these headers. Toolken captures them as attribution data with no extra configuration required. They are forwarded to the provider unchanged and are not stripped. These are the lowest-priority source for each key. If you also send X-Toolken-Metadata-Session-Id (or any other metadata header that sets the same key), your value takes precedence. The IDs identify sessions and agents, not individual people.

​
customer_id precedence

When multiple sources set customer_id, the gateway applies this order (highest priority first):
  1. metadata.customer_id in the JSON request body
  2. customer_id key inside the X-Toolken-Metadata header JSON object
  3. X-Toolken-Metadata-Customer-Id header (or legacy X-Toolken-Meta-Customer-Id)

​
Reserved keys

Two metadata keys have dedicated typed storage and are always indexed at high cardinality: Every other key you send (agent, customer_id, feature, tier, or anything else) is stored as a metadata property and is equally filterable and groupable in the dashboard. There is no required list of keys — send any key that makes sense for your system and it appears in the group-by controls automatically.

​
Metadata limits

The metadata you attach through X-Toolken-Metadata and X-Toolken-Metadata-* follows a few limits:
  • Up to 16384 bytes total (the serialized JSON object).
  • Up to 64 keys.
  • Each key must match ^_?[a-z][a-z0-9_]{0,63}$ — optional leading underscore, then start with a lowercase letter, followed by lowercase letters, digits, and underscores, up to 64 characters, plus an optional leading underscore. The reserved keys environment and session_id must be set through X-Toolken-Metadata-Environment and X-Toolken-Metadata-Session-Id instead of X-Toolken-Metadata.
If the X-Toolken-Metadata value is not valid JSON, it is ignored silently and the request still goes through with no error. A well-formed JSON object that breaks one of the rules above — an invalid key, more than 64 keys, or over 16384 bytes — is rejected with 422 invalid_metadata. Validate the JSON on your side before sending, since malformed JSON is dropped without an error.