---
title: Authentication for agents
description: How an agent obtains, uses, and revokes a Bird credential, and which OAuth 2.0 grants Bird supports.
canonical: https://bird.com/auth.md
---

# auth.md

Bird is an OAuth 2.0 authorization server. An agent acting for a user gets a
scoped access token through a standard grant, with no Bird-specific handshake to
learn. Everything below is discoverable from metadata, so an agent does not have
to hardcode a URL.

The issuer is `https://platform.bird.com`. Note that it is not `bird.com`:
`bird.com` publishes this document and mirrors the discovery URL, but the
authorization server lives on the platform host, and the `issuer` in its metadata
is the value to trust.

## Discover

Fetch the RFC 8414 authorization server metadata:

```
GET https://platform.bird.com/.well-known/oauth-authorization-server
```

It returns the endpoints, `grant_types_supported`, `code_challenge_methods_supported`,
and `scopes_supported`. Read the endpoints from there rather than from this page.

Coming from the API instead, a `401` names the metadata for you:

```
WWW-Authenticate: Bearer resource_metadata="https://platform.bird.com/.well-known/oauth-protected-resource"
```

That RFC 9728 document lists the `authorization_servers` to use and the same
`scopes_supported`, so an agent can start from an unauthenticated call and reach
the right server without prior knowledge.

## Pick a method

Bird supports three grants, and `grant_types_supported` is the authority:

- **`authorization_code`** with PKCE `S256`, for an agent that can open a browser.
  A loopback redirect (`127.0.0.1`, `[::1]`, `localhost`) is accepted for a native
  client, per RFC 8252.
- **`urn:ietf:params:oauth:grant-type:device_code`**, for a headless agent. Bird
  shows the user a code to confirm in a browser on another device.
- **`refresh_token`**, to continue without asking the user again. Refresh tokens
  rotate on every use.

PKCE `S256` is required for a public client. The `plain` method is not supported.

There is no client-credentials grant and no assertion grant. An agent always acts
for a user who consented, which is what makes a token revocable by that user.

## Register

An agent with no pre-issued client can register itself at runtime under RFC 7591:

```
POST https://platform.bird.com/v1/oauth/register
```

A registered client is public and its `client_name` is self-asserted, so Bird's
consent screen tells the user which claims it can and cannot vouch for.

An MCP host does not need to do this by hand. Connecting to `https://mcp.bird.com`
runs discovery and registration for you.

## Claim

Bird has no separate claim endpoint. User verification happens inside the grant
itself: the browser consent screen for `authorization_code`, and the user-code
ceremony for the device grant. If you are looking for a `claim_uri`, the device
authorization endpoint is the equivalent step.

## Use the credential

Send the access token as a bearer token:

```
Authorization: Bearer bt_{region}_...
```

The prefix carries the region, so the token itself tells you which host to call.
Scopes are `resource:level` pairs, for example `emails:write` or `domains:read`.
Request only what the task needs: consent caps whatever you ask for to what the
user actually holds, so an over-broad request is narrowed rather than granted.

## Errors

Failures arrive as RFC 6749 error responses, and the code says whether retrying
can help:

- `invalid_grant`, `invalid_client`, `invalid_scope`: the request will not succeed
  as written. Change it.
- `insufficient_scope` on an API call: the token is real but too narrow. Ask for
  the missing scope.
- `401` with a `WWW-Authenticate` header: start at Discover above.

Bird's API errors carry a machine-readable code and a documentation link, so an
agent can branch without parsing prose. The full catalogue is at
[bird.com/docs/api/errors](https://bird.com/docs/api/errors).

## Revocation

Either side can end the grant.

An agent revokes its own token:

```
POST https://platform.bird.com/v1/oauth/revoke
```

A user revokes an agent's access from the Bird dashboard's connected
applications view, which invalidates the whole grant family rather than one token.
Reusing a rotated refresh token is treated as compromise and revokes the family
too, so an agent should hold exactly one live refresh token per grant.

## More

- [MCP server](https://bird.com/docs/ai/mcp-server), the fastest path for an agent that speaks MCP
- [CLI for agents](https://bird.com/docs/ai/cli-for-agents), the same API from a shell
- [llms.txt](https://bird.com/llms.txt), the curated index of Bird's agent surfaces
- [OpenAPI](https://bird.com/openapi.json), every endpoint and error code