OAuth discovery

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.

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.

Authorization server metadata

The authorization server metadata follows RFC 8414. It lives at the domain root, not under /v1:

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`.
`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`.
`registration_endpoint`	`https://api.guild.ai/v1/oauth/register`	Where the client registers itself with dynamic client registration. See `POST /oauth/register`.
`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.

Example response:

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

curl https://api.guild.ai/.well-known/oauth-protected-resource/mcp

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

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

Get Started

OAuth

Workspaces

Triggers

Agents

Agent versions

Sessions

Skills

Integrations

Accounts

Organizations and users

Customer connectors

OAuth discovery

Authorization server metadata

Protected resource metadata

How a client connects

​Authorization server metadata

​Protected resource metadata

​How a client connects

Authorization server metadata

Protected resource metadata

How a client connects