# auth.md

Authentication and agent-registration guide for chirpwireless.io and the CHIRP platform.

## Who this is for

AI agents and developers that need credentials to use CHIRP services on behalf of a user.

## Services at a glance

- **Landing site (this host)** — public marketing content; no authentication required. Machine-readable alternates: [/llms.txt](https://chirpwireless.io/llms.txt), [/llms-full.txt](https://chirpwireless.io/llms-full.txt).
- **CHIRP MCP server** — `https://mcp-auth.chirpwireless.io/mcp` (Streamable HTTP). OAuth 2.1 with automated dynamic client registration; see below.
- **Public REST API** — `https://api.chirpwireless.io` (OpenAPI: https://api.chirpwireless.io/openapi.yaml). Requires an API key created by a human account owner.
- **Web app** — https://app.chirpwireless.io. Human sign-in via CHIRP ID (OIDC).
- **Docs** — https://docs.chirpwireless.io/ (includes a public, unauthenticated docs MCP endpoint at `https://docs.chirpwireless.io/~gitbook/mcp`).

## Agent registration (MCP server, automated)

The CHIRP MCP server supports the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization): OAuth 2.1 authorization-code flow with PKCE and Dynamic Client Registration (RFC 7591). No manual credential setup is needed — a compliant MCP client discovers everything from the endpoint:

1. Connect to `https://mcp-auth.chirpwireless.io/mcp`. The server answers `401` with `WWW-Authenticate` pointing at its Protected Resource Metadata (RFC 9728): https://mcp-auth.chirpwireless.io/.well-known/oauth-protected-resource
2. Fetch the authorization server metadata (RFC 8414): https://mcp-auth.chirpwireless.io/.well-known/oauth-authorization-server
3. Register a client at `https://mcp-auth.chirpwireless.io/register` (Dynamic Client Registration; CIMD `client_id` URLs are also accepted).
4. Run the authorization-code + PKCE flow (`/authorize`, `/token`); the human signs in with their CHIRP account.
5. Call the MCP server with the Bearer access token. Users in multiple organizations can target one explicitly via `https://mcp-auth.chirpwireless.io/o/{orgId}/mcp`; the plain `/mcp` URL uses the default organization.

## Public REST API (API keys, human-issued)

There is no automated registration for the REST API. A human account owner must:

1. Sign up or sign in at https://app.chirpwireless.io.
2. Create an API key in the app (see the "Authentication and API keys" page at https://docs.chirpwireless.io/).

Send the API key and organization ID as request headers on every call. The exact header names are defined by the `ApiKeyAuth` and `OrgId` security schemes in the OpenAPI specification: https://api.chirpwireless.io/openapi.yaml

## OAuth / OIDC

Interactive user sign-in uses the CHIRP identity provider (issuer `https://id.chirpwireless.io`):

- Authoritative OIDC discovery: https://id.chirpwireless.io/.well-known/openid-configuration
- Token endpoint: https://id.chirpwireless.io/oauth/v2/token
- JWKS: https://id.chirpwireless.io/oauth/v2/keys

For discovery convenience, copies of the relevant metadata are also served on this host at [/.well-known/openid-configuration](https://chirpwireless.io/.well-known/openid-configuration) (CHIRP ID) and [/.well-known/oauth-authorization-server](https://chirpwireless.io/.well-known/oauth-authorization-server) (MCP authorization gateway). The authoritative documents live on their own hosts, listed above.

## Related discovery documents

- [/.well-known/oauth-protected-resource](https://chirpwireless.io/.well-known/oauth-protected-resource)
- [/.well-known/api-catalog](https://chirpwireless.io/.well-known/api-catalog)
- [/.well-known/mcp/server-card.json](https://chirpwireless.io/.well-known/mcp/server-card.json)
- [/.well-known/agent-skills/index.json](https://chirpwireless.io/.well-known/agent-skills/index.json)