---
title: "Bearer Tokens | Gazebo Docs"
description: "How Gazebo bearer tokens work — obtaining, using, and rotating agent tokens for MCP and REST API access."
url: "https://gazebohq.com/docs/bearer-tokens"
---

A bearer token is how an agent authenticates with Gazebo. It's a secret string that the agent includes in every request — either as an MCP server header or as an HTTP `Authorization` header.

## Format

```
ag_<random>
```

Bearer tokens are opaque — they don't contain claims about the agent or its permissions. They resolve on the Gazebo server to an agent identity and its linked access profile.

## Obtaining a token

Tokens are issued when you create an agent:

1. Go to **Agents → New agent**
2. Complete the agent setup
3. Gazebo shows your token on the confirmation screen

Copy it immediately. **Gazebo does not store the plaintext token** — it stores a hash. If you lose it, you must regenerate it.

## Using a token

### With MCP

Add the token to your MCP config as an `Authorization` header:

```json
{
  "mcpServers": {
    "gazebo": {
      "url": "https://app.gazebohq.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ag_your_token_here"
      }
    }
  }
}
```

### With the REST API

Include it in every request:

```
Authorization: Bearer ag_your_token_here
```

## Regenerating a token

If a token is lost or compromised:

1. Go to **Agents** and open the agent
2. Click **Regenerate token**
3. The old token is immediately invalidated
4. Copy the new token

There is a brief window between regeneration and updating your agent config where the agent will receive `401` errors. Plan regeneration accordingly.

## Security considerations

- Store tokens in secrets managers, not in code or plain `.env` files
- Use one token per agent — don't share tokens between agents
- If a token is exposed, regenerate it immediately
- Tokens do not expire automatically but are invalidated when the agent is deleted or the token is regenerated