> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# OAuth discovery

> The metadata documents MCP clients read to find Guild's OAuth endpoints, scopes, and PKCE requirements.

Guild publishes OAuth 2.0 metadata so Model Context Protocol (MCP) clients such as Claude or Cursor can configure themselves. A client reads the metadata, registers itself, and runs the authorization code flow without any manual setup.

Both metadata documents are public. You don't need credentials to read them.

<Note>
  OAuth is for MCP clients acting on behalf of a person. To call the REST API from your own code, use an account API key instead. See [Authentication](/api-reference/introduction#authentication).
</Note>

## Authorization server metadata

The authorization server metadata follows [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). It lives at the domain root, not under `/v1`:

```bash theme={null}
curl https://api.guild.ai/.well-known/oauth-authorization-server
```

| Field | Value | Description |
| - | - | - |
| `issuer` | `https://api.guild.ai` | The authorization server's issuer identifier. |
| `authorization_endpoint` | `https://api.guild.ai/v1/oauth/authorize` | Where the client sends the person to approve access. See [`GET /oauth/authorize`](/api-reference/oauth/start-an-oauth-authorization-by-redirecting-to-the-consent-page). |
| `token_endpoint` | `https://api.guild.ai/v1/oauth/token` | Where the client exchanges an authorization code or refresh token for an access token. See [`POST /oauth/token`](/api-reference/oauth/exchange-an-authorization-code-or-refresh-token-for-an-access-token). |
| `registration_endpoint` | `https://api.guild.ai/v1/oauth/register` | Where the client registers itself with dynamic client registration. See [`POST /oauth/register`](/api-reference/oauth/register-an-oauth-client). |
| `response_types_supported` | `["code"]` | Guild supports the authorization code flow only. |
| `grant_types_supported` | `["authorization_code", "refresh_token"]` | The grant types the token endpoint accepts. |
| `code_challenge_methods_supported` | `["S256"]` | Every authorization must use PKCE (Proof Key for Code Exchange) with SHA-256. |
| `token_endpoint_auth_methods_supported` | `["none"]` | Clients are public. They hold no secret and prove themselves with PKCE instead. |
| `scopes_supported` | `<group>:<access>` strings | The scopes a client can request, such as `agents:read` or `workspaces:write`. See [Scopes](/api-reference/introduction#scopes). |

Example response:

```json theme={null}
{
  "issuer": "https://api.guild.ai",
  "authorization_endpoint": "https://api.guild.ai/v1/oauth/authorize",
  "token_endpoint": "https://api.guild.ai/v1/oauth/token",
  "registration_endpoint": "https://api.guild.ai/v1/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["agents:read", "agents:write", "sessions:read", "sessions:write", "workspaces:read", "workspaces:write"]
}
```

The example shortens `scopes_supported`. Read the live document for the full list rather than hardcoding it.

## Protected resource metadata

Each OAuth-protected resource also publishes [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) metadata. It names the authorization server and the scopes that resource accepts. The path is the resource's own path, appended to `/.well-known/oauth-protected-resource`:

```bash theme={null}
curl https://api.guild.ai/.well-known/oauth-protected-resource/mcp
```

```json theme={null}
{
  "resource": "https://api.guild.ai/mcp",
  "authorization_servers": ["https://api.guild.ai"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["agents:read", "agents:write", "sessions:read", "workspaces:read"]
}
```

A client usually finds this document from a `401` response. The response's `WWW-Authenticate` header carries a `resource_metadata` link to it.

## How a client connects

1. The client calls the resource without a token and gets a `401` with a `resource_metadata` link.
2. It reads the protected resource metadata to find the authorization server.
3. It reads the authorization server metadata to find the endpoints.
4. It registers itself at the `registration_endpoint`.
5. It sends the person to the `authorization_endpoint` with a PKCE challenge. The person approves the requested scopes on Guild's consent screen.
6. It exchanges the returned code at the `token_endpoint`, then sends the access token as a Bearer token.