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:

{
  "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