> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Understand credentials and keys

> Tell apart the four ways that people and systems authenticate with Fabric AI Gateway, and find the topic for each.

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

| Credential              | What it authenticates                                     | Who uses it                                                                           | Where it goes                                                               |
| ----------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Console sign-in**     | A person who opens the console to configure the gateway   | Operators                                                                             | The console's sign-in page                                                  |
| **Gateway key**         | A caller that sends requests through a route              | Consumers: apps, agents, and tools                                                    | The `fg-api-key` header on each request                                     |
| **Upstream credential** | The gateway, when it calls a provider, MCP server, or API | The gateway, set up by operators. On Passthrough routes, the caller supplies its own. | Stored in a vault, and added to the request that the gateway sends upstream |
| **API key**             | A script or agent that calls the admin API                | Operators and automation                                                              | The `fg-tenant-api-key` header on admin API requests                        |

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](/configure/authentication/key-auth). To send a key, see [Authenticate and send a request](/use/authenticate).

## 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](/configure/credentials). To tell this error from a missing gateway key, see [Troubleshoot access](/use/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](/configure/automation/api-keys) and [Configure the gateway with the admin API](/configure/automation/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](/run/secrets-and-keys).

## Next steps

* [Understand who uses Fabric](/evaluate/who-uses-fabric)
* [Manage credentials and vaults](/configure/credentials)