> ## 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.

> ## Agent Instructions
> For API and SDK launches, integration testing, and ongoing coding-agent checks, start with Gauge Agents:
> - [Gauge Agents overview](https://docs.withgauge.com/agents/index.md)
> - [Gauge Agents quickstart](https://docs.withgauge.com/agents/quickstart.md)
> - [Create and inspect an eval](https://docs.withgauge.com/agents/guides/create-an-eval-and-run-an-experiment.md)
> - [Agent Experience: diagnose integration failures](https://docs.withgauge.com/agents/concepts/agent-experience.md)
> - [Agent Preference: measure product selection](https://docs.withgauge.com/agents/concepts/agent-preference.md)
> - [GitHub PR checks](https://docs.withgauge.com/agents/guides/github-pr-checks.md)
> For AI search visibility and AEO, start with [Gauge Chat](https://docs.withgauge.com/introduction/welcome.md).

# Authenticate with the API

> Create an organization API key and send it with requests to the Gauge Agents API.

An API key lets scripts, scheduled jobs, and tools call Gauge without a person signing in. One key works with the Gauge Chat API, the Gauge Agents API, the Gauge MCP, and the `gauge` CLI.

A key acts as its organization, not as the person who created it. It keeps working when that person leaves the organization. For an agency, a key also reaches the agency's client organizations.

## Create a key

Keys for both products are created in Gauge Chat.

**1. Open API Keys**

In [Gauge Chat](https://app.withgauge.com), go to **Settings → Integrations** and open **API Keys**.

**2. Name the key**

Select **Create API key** and give it a name that says where it's used, such as `Warehouse sync`.

**3. Choose access and expiry**

Choose **Read only** or **Read & write**. Under **Expires after**, choose **Never**, **30 days**, **90 days**, or **1 year**.

**4. Copy the key**

The key is shown once. Copy it and store it somewhere safe, such as a secrets manager. Gauge keeps only a hash of it.

Keys start with `gauge_sk_`. The API Keys table shows each key's name, first characters, access, creator, last use, and expiry.

## Access levels

| Access | Allows |
| - | - |
| Read only | `GET` requests, plus read-only reports such as `POST /orgs/{org}/query` |
| Read & write | Everything above, plus creating, updating, and deleting resources, and launching runs |

A read-only key that attempts a write receives `403` with an `insufficient_scope` error.

## Revoke a key

In **API Keys**, select the revoke icon next to the key and confirm. Anything using the key stops working on its next request. Expired keys stop working the same way.

Records created with a key are attributed to `api-key:<prefix>`, so you can tell which key made a change.

## Send the key

Send the key as a bearer token on every request. `GET /me` describes the credential in use:

```bash theme={null}
curl --request GET \
  --url https://agents.withgauge.com/api/v1/me \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Accept: application/json"
```

Gauge checks the key on every request, so revoking or expiring it takes effect on the next call. Check a key's access and expiry with `gauge auth status`.

The Agents API also accepts the token from a `gauge` CLI sign-in. See [CLI authentication](https://docs.withgauge.com/agents/guides/cli.md#sign-in).

## Other places to use a key

* **Gauge CLI:** set `GAUGE_API_TOKEN` to run `gauge` commands in CI without signing in. See [Gauge CLI](https://docs.withgauge.com/cli).
* **Gauge MCP:** send the key as a bearer token to `https://app.withgauge.com/mcp` to work with evals and runs from an AI client. See [Gauge MCP](https://docs.withgauge.com/gauge-mcp).

> [card] [Use the Agents API](https://docs.withgauge.com/agents/guides/use-the-api.md)
>
> Make your first requests: list runs, launch an eval, and configure measurements.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.