# Compteam authentication

How AI agents and MCP clients obtain and use credentials for Compteam. The four public MCP discovery tools (search_clubs, list_public_classes, list_public_membership_plans, get_public_branch_details) need no credentials. Every account tool requires an OAuth 2.1 access token issued for the Compteam MCP resource.

## Discover

- Protected resource: https://api.compteam.io/mcp
- Protected resource metadata (RFC 9728): https://api.compteam.io/.well-known/oauth-protected-resource
- Authorization server issuer: https://kllgyfbcdnonrvmrftki.supabase.co/auth/v1
- Authorization server metadata (RFC 8414): https://kllgyfbcdnonrvmrftki.supabase.co/auth/v1/.well-known/oauth-authorization-server
- OpenID configuration: https://kllgyfbcdnonrvmrftki.supabase.co/auth/v1/.well-known/openid-configuration

A protected MCP call without a valid token returns HTTP 401 with `WWW-Authenticate: Bearer resource_metadata="https://api.compteam.io/.well-known/oauth-protected-resource"`. Follow resource_metadata to the authorization server, then read its metadata for the authorization, token and registration endpoints.

## Pick a method

Use the OAuth 2.1 authorization-code flow with PKCE (S256). Compteam does not offer API keys, client-credentials grants, password grants or agent identity assertions for account data: a person always signs in and approves the connection.

## Register

Clients that support Dynamic Client Registration register at the registration_endpoint advertised in the authorization server metadata. Automatically registered clients get the reviewed marketplace_safe profile only. Clients that need registration or club-administration tools request manual review at https://compteam.io/documentation/mcp; Compteam approves each registration_full client individually.

## Claim

The person using the agent claims the connection by signing in to their own Compteam account and approving the consent screen. Check the account shown before continuing, or choose Use another account. Never paste passwords, tokens, bank details or service keys into a chat.

## Exchange

Exchange the authorization code at the token_endpoint with the PKCE code_verifier. Request the identity scopes openid, email, profile and set resource to https://api.compteam.io/mcp. Refresh tokens use the refresh_token grant at the same endpoint.

## Use the access_token

Send `Authorization: Bearer <access_token>` on requests to https://api.compteam.io/mcp. The token's audience must be the Compteam MCP resource; website session tokens are rejected. Identity scopes do not grant club-administration rights: the server checks the client's capability profile, club membership, current role, subscription and confirmation rules on every call.

## Errors

- 401 invalid_token: the token is missing, expired or issued for another resource. Re-run the authorization flow; do not retry with a website token.
- Permission errors: the tool result has isError true when the club, the user's role or the client profile does not allow the action. Do not request broader permissions on the user's behalf.
- 429: wait for Retry-After seconds before retrying.
- Demo accounts remain read-only.

## Revocation

Disconnect Compteam in your AI client to stop using its tokens. Compteam can suspend an individual client registration, after which its tokens are rejected. Contact info@compteam.io to remove an approved client.

[Developer guide](https://compteam.io/developers) · [Privacy](https://compteam.io/privacy)