Understand credentials and keys
Fabric AI Gateway uses four kinds of credentials. They have different owners and protect different things, and some have similar names. This topic defines each one and shows where to manage it. Use these names in your own docs and prompts so that people and agents don’t mix them up.
Compare the four credentials
The gateway key and the API key are different keys. A gateway key lets a caller use the gateway, and it can’t change configuration. An API key changes configuration, and it doesn’t send traffic through a route.
Understand the gateway key
A route can be open or require authentication. If it requires authentication, the caller must send a gateway key, or a token from your identity provider if the route uses JWT Auth. If the route is open and it’s in the Default namespace, the caller sends no key. To reach a route in any other namespace, the caller must still send a gateway key in the fg-api-key header, because the key picks the namespace. Without it, the request goes to Default and gets 404. A gateway key gets a caller to the route, but access control still applies: an admin can allow a connection to some callers and not others.
For setup, see Authenticate requests with Key Auth. To send a key, see Authenticate and send a request.
Understand the upstream credential
A gateway-managed upstream credential is the provider’s own key, such as an Anthropic API key, that an operator saved in a vault. On those routes, the caller never sends it, and the gateway adds it to the request. On Passthrough routes, on Lightyear routes with Use the client’s provider credentials on, and on REST routes with no upstream credential configured, the caller’s own provider credential is forwarded. Users can also connect their own accounts for per-user connections. If a request reaches the provider and the provider rejects the credential, the owner of that credential fixes it: an operator for a gateway-managed credential, or the caller for their own provider key or per-user account. For the steps, see Manage credentials and vaults. To tell this error from a missing gateway key, see Troubleshoot access.
Understand the API key
An API key lets a script or agent do what an operator does in the console. It acts for the whole organization. It can’t manage API keys, including listing them, and only a signed-in admin can. For the steps, see Manage API keys and Configure the gateway with the admin API.
Understand the data plane keys
If you run your own data plane, the data plane also holds secrets of its own, such as the key that protects its secret store. These aren’t credentials for callers or operators. For details, see Manage secrets and keys.

