# Endpoints

Every address of Buun Identity a product, an agent or the gateway calls. Paths are on the issuer of each environment, such as `https://id.buungroup.com`.

## Discovery

| Method and path | Answers |
|---|---|
| `GET /.well-known/openid-configuration` | OpenID Connect provider metadata |
| `GET /.well-known/oauth-authorization-server` | The same, for OAuth 2.1 and MCP clients (RFC 8414) |
| `GET /.well-known/jwks.json` | The public keys that verify every token |

The metadata names `buun_plans_endpoint` as well as the standard endpoints, and says `client_id_metadata_document_supported` and `resource_indicators_supported` are true.

## OAuth and OpenID Connect

| Method and path | Who calls it | What it does |
|---|---|---|
| `GET /oauth/authorize` | A browser, sent by a client | Starts a sign-in. Answers a redirect to the client with a code, or to the portal |
| `POST /oauth/token` | A client | Trades a code, a refresh token, or for the gateway an access token, for tokens |
| `POST /oauth/revoke` | A client | Ends a refresh token and its family. Always 200 for a known client |
| `GET /oauth/userinfo` | A client with an access token holding `openid` | `sub`, and `email`, `email_verified`, `name` and `orgs` as the scopes allow |
| `GET /oauth/plans` | A product with an access token | The person's active plans, as far as that client may know |

`/oauth/token`, `/oauth/revoke`, `/oauth/userinfo`, `/oauth/plans` and the discovery addresses answer any origin, so a page or a tool may call them.

## Grant types

| `grant_type` | For |
|---|---|
| `authorization_code` | Every client, with PKCE S256 |
| `refresh_token` | A client that asked for `offline_access` |
| `urn:ietf:params:oauth:grant-type:token-exchange` | The gateway's exchange client only. See [Token exchange](https://developers.buungroup.com/mcp/token-exchange) |

## The gateway

| Method and path | What it does |
|---|---|
| `POST /mcp` | The MCP endpoint, stateless over HTTP: `initialize`, `ping`, `tools/list`, `tools/call` |
| `GET /.well-known/oauth-protected-resource` | The gateway's resource metadata (RFC 9728): its address and Buun Identity as the authorization server |
| `GET /health` | Says the Worker is up |

## Staff only

The issuer's `/admin` and the gateway's `/admin` are called by the staff console alone, with its own token and the acting member of staff named on every call. The issuer's admin API is described as OpenAPI 3.1 at `/admin/openapi.json`. A product never calls either.

Source: https://developers.buungroup.com/reference/endpoints
