OAuth 2.1
Connect Claude, ChatGPT, Codex and other OAuth 2.1 clients to your AWSYS account
The AWSYS MCP server is an OAuth 2.1 protected resource with its own authorization server, following the MCP authorization specification. MCP clients such as Claude.ai, ChatGPT, Codex and Claude Code discover it automatically, sign the user in, and receive tokens bound to the MCP server — no API key to copy.
Existing awsys_... API keys keep working alongside OAuth on the same endpoint.
How It Works
- The client calls the MCP server without a token and receives 401 with a WWW-Authenticate header that points to the protected resource metadata.
- It reads the protected resource metadata, then the authorization server metadata.
- It identifies itself with a Client ID Metadata Document (CIMD) or registers through Dynamic Client Registration (DCR).
- It sends the user to the authorization endpoint with a PKCE S256 challenge. The user signs in to AWSYS and approves the consent screen.
- It exchanges the authorization code for a 15-minute access token and, with the offline_access scope, a refresh token.
- It calls the MCP server with the access token as a Bearer token and refreshes it in the background.
Connecting from an assistant
In Claude.ai, ChatGPT or Codex, add an MCP server or connector with the URL https://awsys.co/mcp and choose OAuth. The assistant discovers everything else. The Help Center guide has step-by-step instructions for each assistant:
Connect AI assistants to your AWSYS account
Discovery Endpoints
These public JSON endpoints need no authentication and allow requests from any origin.
GET /.well-known/oauth-protected-resource
RFC 9728 Protected Resource Metadata. The same document is also served at the path-suffixed location that RFC 9728 derives from the resource URL:
GET /.well-known/oauth-protected-resource/mcp
{
"resource": "https://awsys.co/mcp",
"authorization_servers": ["https://awsys.co"],
"scopes_supported": ["mcp:tools", "mcp:resources", "offline_access"],
"bearer_methods_supported": ["header"]
}
GET /.well-known/oauth-authorization-server
RFC 8414 Authorization Server Metadata. authorization_response_iss_parameter_supported is true (see RFC 9207 below), and client_id_metadata_document_supported is true.
{
"issuer": "https://awsys.co",
"authorization_endpoint": "https://awsys.co/oauth/authorize",
"token_endpoint": "https://awsys.co/oauth/token",
"registration_endpoint": "https://awsys.co/oauth/register",
"revocation_endpoint": "https://awsys.co/oauth/revoke",
"scopes_supported": ["mcp:tools", "mcp:resources", "offline_access"],
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"token_endpoint_auth_methods_supported": ["none"],
"code_challenge_methods_supported": ["S256"],
"client_id_metadata_document_supported": true,
"authorization_response_iss_parameter_supported": true
}
Unauthenticated requests
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://awsys.co/.well-known/oauth-protected-resource"
The WWW-Authenticate header is the entry point for automatic discovery (RFC 9728 §5.1). A token without the mcp:tools scope receives 403 with error="insufficient_scope", and a token whose connection was revoked receives 401 with error="invalid_token".
Client Registration
Every client is a public client: no client secret is issued, the only token endpoint authentication method is none, and PKCE is mandatory. A client identifies itself in one of two ways.
Client ID Metadata Document (CIMD)
Use an https URL as the client_id. AWSYS fetches the JSON document at that URL and validates it:
- The document's client_id must equal the URL it was fetched from.
- Its redirect_uris are enforced exactly, like a registered client. Entries that don't meet the redirect URI rules below are ignored; a document with no usable redirect URI is rejected.
- client_name is shown on the consent screen (up to 100 characters). Without it, the URL's host name is shown.
- The fetch is https only, follows no redirects, times out after 3 seconds and accepts at most 10 KB. Private network addresses are refused.
- Documents are cached for 24 hours. If a refresh fails, a cached copy up to 7 days old is used. A document that can't be fetched or fails validation makes the client unknown (unauthorized_client).
Example document:
GET https://app.example.com/oauth/client.json
{
"client_id": "https://app.example.com/oauth/client.json",
"client_name": "Example Assistant",
"redirect_uris": ["https://app.example.com/oauth/callback"]
}
Dynamic Client Registration (DCR)
Clients that don't use CIMD register with POST /oauth/register (RFC 7591). Registration is rate-limited to 5 requests per minute per IP. Registering the same set of redirect_uris again returns the existing client_id with 200 OK instead of 201 Created.
Request
POST /oauth/register
Content-Type: application/json
{
"redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
"client_name": "Claude.ai",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "none"
}
Response 201 Created
{
"client_id": "550e8400-e29b-41d4-a716-446655440000",
"client_id_issued_at": 1749600000,
"redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "none"
}
No client_secret is issued. A redirect URI that breaks the rules below returns 400 invalid_redirect_uri.
Redirect URI rules
- Redirect URIs must use https. Plain http is allowed only for loopback hosts: localhost, 127.0.0.1 and [::1].
- URIs with a fragment or with user credentials are rejected.
- Matching is exact, except that a loopback redirect may use any port (RFC 8252 §7.3). Claude Code, for example, registers http://localhost/callback and listens on a random port.
Authorization Code Flow
Step 1 — Authorization request
GET /oauth/authorize
?response_type=code
&client_id=550e8400-e29b-41d4-a716-446655440000
&redirect_uri=https://claude.ai/api/mcp/auth_callback
&scope=mcp:tools+offline_access
&state=xyz
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&resource=https://awsys.co/mcp
| Parameter | Required | Notes |
|---|---|---|
response_type | Yes | Must be code. |
client_id | Yes | A DCR client_id or a CIMD URL. |
redirect_uri | Yes | Must match one of the client's redirect URIs. |
code_challenge | Yes | BASE64URL(SHA-256(code_verifier)). |
code_challenge_method | Yes | Must be S256. plain is rejected. |
scope | No | Space-separated. Unknown scopes are ignored; if none is valid, mcp:tools is used. |
state | Recommended | Returned unchanged. |
resource | No | RFC 8707. If sent, must be https://awsys.co/mcp; otherwise invalid_target. |
Until the client and redirect URI are confirmed (missing parameters, unknown client_id, disallowed or unregistered redirect_uri), errors are shown on an AWSYS error page instead of being redirected to the client. The endpoint is rate-limited to 30 requests per minute per IP.
Step 2 — User consent
AWSYS shows a consent screen with the client's name. The user signs in if needed and clicks Allow Access or Deny within 5 minutes. The browser is then redirected to the redirect_uri:
Approved:
https://claude.ai/api/mcp/auth_callback?code=AUTH_CODE&state=xyz&iss=https%3A%2F%2Fawsys.co
Denied:
https://claude.ai/api/mcp/auth_callback?error=access_denied&error_description=User+denied+authorization&state=xyz&iss=https%3A%2F%2Fawsys.co
The iss parameter (RFC 9207)
Every redirect back to the client, success or error, carries iss set to the issuer, https://awsys.co. Clients should check that it equals the issuer in the authorization server metadata before using the code. ChatGPT relies on it to use its stable client ID and callback URL.
Authorization codes are single-use and expire after 60 seconds.
Step 3 — Token exchange
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://claude.ai/api/mcp/auth_callback
&client_id=550e8400-e29b-41d4-a716-446655440000
&code_verifier=ORIGINAL_VERIFIER
&resource=https://awsys.co/mcp
The token endpoint accepts application/x-www-form-urlencoded. code, redirect_uri, client_id and code_verifier are required; resource is optional and follows the same rule as above.
Response 200 OK
{
"access_token": "eyJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 900,
"scope": "mcp:tools offline_access",
"refresh_token": "dBjftJeZ4CVP-mB92K27uhb..."
}
The resource parameter (RFC 8707)
Access tokens are bound to the MCP server: their audience is https://awsys.co/mcp. Clients may send resource on the authorization request and on token requests. When present, it must be exactly https://awsys.co/mcp; any other value is rejected with invalid_target. Omitting it is allowed.
HTTP/1.1 400 Bad Request
{ "error": "invalid_target", "error_description": "resource must be https://awsys.co/mcp" }
Scopes
| Scope | What it grants |
|---|---|
mcp:tools | Call the MCP tools the user's plan includes. Required for every MCP request. |
mcp:resources | Reserved for MCP resources (none are exposed yet). |
offline_access | Issues a refresh token. Without it, no refresh token is returned and the client must authorize again after 15 minutes. |
Token Lifecycle
| Token | Lifetime | Notes |
|---|---|---|
| Access token (JWT) | 15 minutes | Signed JWT whose audience is the MCP server. Each MCP call also checks the account, so a disconnected app or a suspended account loses access immediately. |
| Refresh token | 30 days, sliding | Opaque and single-use. Every refresh returns a new refresh token valid for another 30 days, so a connection lasts until it is revoked or goes unused for 30 days. |
| Authorization code | 60 seconds | Single-use; verified against the PKCE code_verifier. |
| Consent screen session | 5 minutes | Single-use; the OAuth parameters are stored server-side. |
Token Refresh
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=CURRENT_REFRESH_TOKEN
Returns a new access token and a new refresh token; the old refresh token stops working. Rotation is replay-protected: presenting a refresh token that was already used revokes the whole grant, meaning every token issued from that consent. A retry within 10 seconds of a successful rotation, such as two concurrent refreshes, receives invalid_grant without revoking the grant.
Expired, revoked or unknown refresh tokens, and refreshes for a suspended account, return 400 invalid_grant.
Token Revocation
POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded
token=REFRESH_TOKEN_TO_REVOKE
Revoking a refresh token (RFC 7009) ends the whole grant it belongs to, including its access tokens. The endpoint always returns 200 OK and never reveals whether the token was valid.
Users can also disconnect an app in AWSYS under Settings → Developer → Connected apps. That takes effect immediately, including for access tokens that haven't expired yet.
ChatGPT and Codex
ChatGPT identifies itself with the CIMD client_id https://chatgpt.com/oauth/client.json; its redirect URIs come from that document (https://chatgpt.com/connector_platform_oauth_redirect). Clients identified as OpenAI receive the curated OpenAI tool profile instead of the full tool set:
Backward Compatibility
The MCP server accepts both OAuth access tokens and existing awsys_... API keys in the same Authorization: Bearer header. A Bearer value that starts with awsys_ is treated as an API key; anything else is validated as an OAuth access token first. No migration is required for existing integrations.
Claude Code (CLI)
Claude Code uses a loopback redirect URI such as http://localhost:PORT/callback, and any port is accepted. The flow is identical to the one above, and PKCE is required.