Authentication & Credentials
The two-credential model (ACE dev key vs. upstream provider key), provider key resolution order, the ace_dev_ / ace_tok_ prefix discriminator, and header precedence.
ACE uses two credentials that do two different jobs. Conflating them is the most common integration error.
| Credential | Header | Identifies | Required for |
|---|---|---|---|
| ACE developer key | Authorization: Bearer ace_dev_... | your org (tenant) to ACE | every authenticated endpoint |
| Provider key (pass-through) | x-ace-openai-key / x-ace-anthropic-key / x-ace-google-key | which upstream LLM account to bill | real (non-echo) inference, unless you have stored a vendor key |
Provider key resolution. Pass-through header on this request → your tenant's stored vendor key → reject. Pass-through keys are used for that one call and never persisted or logged (zero-knowledge mode), so there is nothing to onboard if you always send one.
Key prefixes. Two prefixes count as an ACE key: ace_dev_ (what the dashboard mints, and what every key you hold looks like) and ace_tok_ (env-seeded deployment keys). A credential starting with neither is treated as a provider key, leaving the request with no ACE identity — which is a 401.
Vendor-shaped surfaces. The vendor-shaped surfaces accept the ACE dev key on the header their SDK already sends, which is what makes the drop-in one line: /anthropic/v1/messages reads x-api-key, /azure/openai/… (chat completions and /azure/openai/v1/responses alike) reads api-key, and /v1/responses reads Authorization: Bearer exactly as /v1/chat/completions does. An ACE key prefix there is your ACE identity; any other value is treated as a pass-through provider key.
Precedence. An Authorization: Bearer header you set yourself always wins. Sending both is the normal pass-through shape — bearer carries your ACE identity, x-api-key / api-key carries the provider credential. A synthesized value only ever fills a gap; nothing overwrites a header you set.
Relay exception. POST /v1/messages is the exception, and it is not the recommended proxy: it exists for parity testing, not production traffic. Being a relay, it preserves however you presented your credential and never rewrites it — and it forwards the body unmodified, so no ACE lever runs on it. Production Anthropic traffic belongs on /anthropic/v1/messages, which accepts the same SDK, carries thinking, tools, images and cache_control as sent, returns Anthropic's own answer, and gets the full lever set.