> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withgauge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials

> Understand how Gauge limits access to the credentials your coding agents need.

Credentials let coding agents use authenticated APIs and hosted MCP servers during a run. A credential belongs to your organization, and you decide which service and coding scenarios may use it.

The central promise is:

> An authorized agent can use a credential for its intended service without receiving the raw secret value.

## How Gauge protects credentials

| Protection             | What it means                                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Organization isolation | A credential belongs to one organization. It is not shared with other organizations or unrelated runs.                                |
| Explicit access        | A credential is available only when you select it for a coding scenario or associate it with an MCP server used by that scenario.     |
| Domain restriction     | You approve the exact service domain that may receive the credential. Gauge does not release it to other destinations.                |
| Secret separation      | The raw value is not added to the agent's prompt, repository, or configuration files. The agent references a credential name instead. |
| Customer control       | Your organization can rotate, reauthorize, or delete credentials from **Settings → Credentials**.                                     |

Gauge uses a stored credential only to support the scenarios and integrations your organization configures. The credential remains governed by the permissions and OAuth scopes you chose at the service that issued it.

## How credentials are used

<Steps>
  <Step title="Add a credential">
    Add an API key or token, or sign in to a hosted MCP service with OAuth. After an API key is saved, Gauge shows only masked identifying information rather than displaying the value again.
  </Step>

  <Step title="Approve its destination">
    Choose the service that may receive the credential. For a custom service, Gauge uses the hostname from the service URL as the boundary.
  </Step>

  <Step title="Choose where it is available">
    Select the credential in a coding scenario when an agent needs to call the API directly. If a hosted MCP server requires the credential, associating it with that server makes it available to scenarios that use the server.
  </Step>

  <Step title="Run with limited access">
    The agent can authenticate to the approved service, but it does not receive the raw secret. Attempts to use the credential with another destination are refused.
  </Step>
</Steps>

## Domain scoping

Credential access is restricted to an exact host. If you approve `api.example.com`, the credential can be used at any path on that host, but not at `example.com`, `other.example.com`, or an unrelated destination.

Domain scoping limits where Gauge will send the credential. It does not reduce what the credential can do after it reaches the approved service. Create vendor credentials with the narrowest permissions or OAuth scopes that the task requires.

<Info>
  A credential is still a capability. An authorized run can perform actions that the credential permits on the approved service, even though the agent cannot view or copy the secret itself.
</Info>

## API keys and MCP OAuth

| Type             | Customer-visible behavior                                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key or token | Paste the value once, then identify it by its name and masked ending. You can rotate it without reconfiguring the scenarios that use it.                                        |
| MCP OAuth        | Sign in through the MCP service and review the access it requests. Gauge maintains the authorization for the integration and asks you to reauthorize if it can no longer do so. |

Some OAuth services require you to create an OAuth application first. In that case, Gauge provides the callback URL to register and asks for the client ID and, when required, the client secret.

## Manage access over time

Manage organization credentials under **Settings → Credentials**.

* Rotate a pasted key or token when its value changes. New runs use the replacement without changing the scenario's credential selection.
* Reauthorize an OAuth credential when Gauge reports that the authorization needs attention.
* Delete a credential to remove it from scenarios and revoke its use. Gauge prevents deletion while a live MCP server depends on it so you can remove or update that dependency first.