OAuth 2.1

Bedrock supports OAuth 2.1 authorization code flow with PKCE for third-party integrations like Microsoft 365 Copilot, ChatGPT, and Claude. OAuth lets external AI agents authenticate to the Bedrock API on behalf of an organization.

When to Use OAuth vs API Keys

	API Keys	OAuth 2.0
Use case	Direct API access, scripts, CI/CD	Third-party integrations (Copilot, ChatGPT, Claude)
Who creates credentials	You, in the Bedrock dashboard	Automated via dynamic registration or pre-configured
Token lifetime	Long-lived (with optional rotation)	Short-lived access (1 hour) + refresh token
Authentication	`Authorization: Bearer sk_...`	`Authorization: Bearer oat_...`

Discovery (MCP Auth Spec)

AI copilots discover Bedrock’s OAuth configuration automatically using well-known metadata endpoints.

Protected Resource Metadata

GET /.well-known/oauth-protected-resource

Returns:

{
  "resource": "https://api.bedrock.cv",
  "authorization_servers": ["https://api.bedrock.cv"],
  "scopes_supported": ["read", "write"],
  "bearer_methods_supported": ["header"]
}

Authorization Server Metadata

GET /.well-known/oauth-authorization-server

Returns:

{
  "issuer": "https://api.bedrock.cv",
  "authorization_endpoint": "https://app.bedrock.cv/oauth/authorize",
  "token_endpoint": "https://api.bedrock.cv/oauth/token",
  "registration_endpoint": "https://api.bedrock.cv/oauth/register",
  "revocation_endpoint": "https://api.bedrock.cv/oauth/revoke",
  "scopes_supported": ["read", "write"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none"],
  "code_challenge_methods_supported": ["S256"]
}

WWW-Authenticate Header

Unauthenticated requests to protected endpoints return:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.bedrock.cv/.well-known/oauth-protected-resource"

Client Registration

Bedrock supports three methods for registering OAuth clients:

Static Clients

Pre-registered for known partners (e.g., Microsoft Copilot). These are seeded in the database with a fixed slug as the client_id.

Dynamic Client Registration (RFC 7591)

Clients like Claude self-register by POSTing to /oauth/register:

POST /oauth/register
Content-Type: application/json

{
  "client_name": "Claude",
  "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Response:

{
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_name": "Claude",
  "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Client ID Metadata Documents (CMID)

Clients like ChatGPT use a URL as their client_id. When Bedrock encounters a URL-based client_id, it fetches the metadata document to validate the client and its redirect URIs.

Authorization Code Flow with PKCE

AI copilot discovers OAuth config via well-known endpoints
Copilot registers as a client (DCR or CMID)
Copilot redirects user to Bedrock consent screen
User logs in, selects organization, and authorizes
Consent screen signs an authorization code and redirects to copilot callback
Copilot exchanges code + PKCE verifier for access token
Copilot uses access token to call Bedrock API
When token expires, copilot uses refresh token to get a new one

Step 1: Authorization

The copilot redirects the user to the consent screen:

https://app.bedrock.cv/oauth/authorize
  ?response_type=code
  &client_id=550e8400-e29b-41d4-a716-446655440000
  &redirect_uri=https://claude.ai/api/mcp/auth_callback
  &scope=read
  &state=random_csrf_token
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

The user logs in (if needed), sees the client name and requested permissions, selects an organization, and clicks Authorize or Deny. On approval, the consent screen signs a PKCE-bound authorization code and redirects directly to the client’s callback:

302 redirect to redirect_uri?code=...&state=...

Step 2: Token Exchange

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=abc123
&redirect_uri=https://claude.ai/api/mcp/auth_callback
&client_id=550e8400-e29b-41d4-a716-446655440000
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Response:

{
  "access_token": "oat_a1b2c3...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ort_d4e5f6...",
  "scope": "read"
}

Step 3: Use the Access Token

curl https://api.bedrock.cv/mcp \
  -H "Authorization: Bearer oat_a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_projects","arguments":{}},"id":1}'

Step 4: Refresh

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=ort_d4e5f6...
&client_id=550e8400-e29b-41d4-a716-446655440000

Returns a new access/refresh token pair. The old refresh token is revoked.

Step 5: Revoke

POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=oat_a1b2c3...

Always returns 200 OK, even if the token was already revoked or not found (per RFC 7009).

Scopes

Scope	Permissions
`read`	Read projects, drawings, sheets, blocks, features, overlays, jobs, organizations
`write`	Create/update projects, drawings, files, jobs

Platform Compatibility

	ChatGPT	Claude.ai / Cowork	Claude Code	Microsoft Copilot
Registration	CMID preferred, DCR fallback	DCR	DCR or pre-configured	Pre-registered (static)
PKCE	Required (S256)	Required (S256)	Required (S256)	Optional

Security

All tokens are stored as SHA-256 hashes (never in plaintext)
Access tokens expire after 1 hour
Refresh tokens expire after 30 days
PKCE (S256) is required for all authorization requests
Authorization codes expire after 10 minutes
Tokens are scoped to a specific organization (selected during consent)

Getting Started

CMS API

Vision API

Errors

When to Use OAuth vs API Keys

Discovery (MCP Auth Spec)

Protected Resource Metadata

Authorization Server Metadata

WWW-Authenticate Header

Client Registration

Static Clients

Dynamic Client Registration (RFC 7591)

Client ID Metadata Documents (CMID)

Authorization Code Flow with PKCE

Step 1: Authorization

Step 2: Token Exchange

Step 3: Use the Access Token

Step 4: Refresh

Step 5: Revoke

Scopes

Platform Compatibility

Security

​When to Use OAuth vs API Keys

​Discovery (MCP Auth Spec)

​Protected Resource Metadata

​Authorization Server Metadata

​WWW-Authenticate Header

​Client Registration

​Static Clients

​Dynamic Client Registration (RFC 7591)

​Client ID Metadata Documents (CMID)

​Authorization Code Flow with PKCE

​Step 1: Authorization

​Step 2: Token Exchange

​Step 3: Use the Access Token

​Step 4: Refresh

​Step 5: Revoke

​Scopes

​Platform Compatibility

​Security

When to Use OAuth vs API Keys

Discovery (MCP Auth Spec)

Protected Resource Metadata

Authorization Server Metadata

WWW-Authenticate Header

Client Registration

Static Clients

Dynamic Client Registration (RFC 7591)

Client ID Metadata Documents (CMID)

Authorization Code Flow with PKCE

Step 1: Authorization

Step 2: Token Exchange

Step 3: Use the Access Token

Step 4: Refresh

Step 5: Revoke

Scopes

Platform Compatibility

Security