Authentication

​

What your server must do

1. Return 401 with a challenge for requests that have no valid token:
   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource/mcp"
   
2. Publish protected-resource metadata (RFC 9728). The document goes at /.well-known/oauth-protected-resource, with your resource path appended when your endpoint is not at the root:
   {
     "resource": "https://example.com/mcp",
     "authorization_servers": ["https://auth.example.com"],
     "scopes_supported": ["invoices:read"],
     "bearer_methods_supported": ["header"],
     "resource_name": "Example Invoices"
   }
   
3. Publish authorization-server metadata (RFC 8414) at /.well-known/oauth-authorization-server on the authorization server (/.well-known/openid-configuration is also read). Include authorization_endpoint, token_endpoint, and code_challenge_methods_supported: ["S256"]. If you accept client ID metadata documents, set client_id_metadata_document_supported: true.
4. Validate every access token. Check the signature, issuer, expiry, and that the audience (aud) is your MCP resource URL. Reject tokens minted for another resource. Return 403 with insufficient_scope when a token lacks the scope a tool needs.

​

What Allternit does

1. Discovery. It fetches /.well-known/oauth-protected-resource on your server’s origin and takes the first entry of authorization_servers. If that document is missing, it uses your server’s origin as the authorization server. It then reads /.well-known/oauth-authorization-server (then /.well-known/openid-configuration) on that issuer for authorization_endpoint and token_endpoint. If neither is found, it falls back to <issuer>/authorize, and to token-endpoint discovery under your MCP server URL (/.well-known/oauth-authorization-server, then /oauth/token, /token, /v1/token).
2. Authorization request. It redirects the user’s browser to your authorization_endpoint with these query parameters:

   Parameter	Value
   response_type	code
   client_id	Allternit’s client ID (see below)
   redirect_uri	Allternit’s callback (see below)
   state	A random value, checked on return
   code_challenge	SHA-256 of a random verifier, base64url
   code_challenge_method	S256
   resource	Your MCP server URL, as registered in the connector

3. Callback. Your authorization server redirects back with code and state. Allternit exchanges the code at the token_endpoint from your authorization-server metadata (grant_type=authorization_code, code, code_verifier, redirect_uri, resource, state, and client_id), then stores the tokens encrypted. When an access token expires, Allternit uses your refresh token at the same endpoint, again with resource. Tokens are used only in an Authorization: Bearer header on requests to your server, and are never logged or returned to the browser.

​

Client ID metadata documents

{
  "client_id": "https://api.allternit.com/oauth/client.json",
  "client_name": "Allternit",
  "client_uri": "https://api.allternit.com",
  "redirect_uris": ["https://api.allternit.com/mcp/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

• sets client_id_metadata_document_supported: true in its metadata,
• fetches the client_id URL when it sees one,
• checks that the redirect_uri in the request is listed in redirect_uris,
• treats the client as a public client (token_endpoint_auth_method: none) and requires PKCE.

​

Dynamic client registration

{
  "redirect_uris": ["https://api.allternit.com/mcp/oauth/callback"],
  "client_name": "Allternit",
  "client_uri": "https://api.allternit.com",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "application_type": "web"
}

​

Redirect URI

​

How users connect

1. The user adds your server (from a plugin package or a directory listing) as a connector.
2. Allternit creates the connector for your server URL and starts the flow above.
3. The user signs in and approves access on your authorization server.
4. Allternit stores the token. From then on, tool calls to your server carry it.

​

Permission prompts

​

Testing your OAuth setup

• Fetch your two metadata documents with curl and confirm resource matches your MCP URL exactly.
• Call your endpoint with no token and confirm you get 401 with a resource_metadata parameter.
• Run the flow with a tool such as the MCP Inspector before you connect it in Allternit.
• After connecting, call a tool and check that your server sees a token whose aud is your resource URL.