# SitePerto auth.md

## Audience and supported authentication

For AI agents and MCP clients acting for a person who chooses SitePerto.
Public guides and catalogs require no registration or credential.
Access to a person's site requires OAuth 2.0 Authorization Code with PKCE S256,
explicit consent and selection of one site. Anonymous access to private sites is not supported.
This document describes the existing OAuth flow, not the WorkOS agent identity/claim protocol.

## Discover

- MCP resource: https://api.storeexperts.com.br/mcp
- Protected resource metadata: https://api.storeexperts.com.br/.well-known/oauth-protected-resource/mcp
- Authorization server metadata: https://api.storeexperts.com.br/.well-known/oauth-authorization-server
- Canonical issuer: https://api.storeexperts.com.br/
- User guide: https://siteperto.com/guias/conectar-ia-local

## Register the OAuth client

POST https://api.storeexperts.com.br/register with Content-Type: application/json.
Supply client_name, redirect_uris, token_endpoint_auth_method: "none",
grant_types: ["authorization_code", "refresh_token"], response_types: ["code"].
Use an HTTPS callback under the client's control, or a supported local loopback callback.
Do not register during passive discovery. Registration creates an expiring client record;
it does not create a user account, grant access, or issue a site access token.

## Obtain consent and credentials

Generate a random state and a PKCE verifier; derive code_challenge using S256.
Open the advertised authorization_endpoint with response_type=code, client_id,
redirect_uri, state, code_challenge, code_challenge_method=S256,
resource=https://api.storeexperts.com.br/mcp, and the minimum scope required.
The person signs in, chooses the site and approves the permissions.
Validate state on return. Exchange the code at the advertised token_endpoint using
grant_type=authorization_code, client_id, redirect_uri, code_verifier and resource.
Never collect the person's password or bypass the consent screen.

## Use, refresh and revoke

Send Authorization: Bearer <access_token> only to the canonical API over HTTPS.
site.read allows reading; site.update allows preparing an update for human review.
Discover tools using MCP tools/list after authentication. No tool publishes a site.
Respect expires_in. Refresh with grant_type=refresh_token, client_id, refresh_token
and resource. Replace the stored refresh token on every successful rotation.
Reusing an old refresh token can revoke the connection; do not retry it blindly.
Revoke using POST https://api.storeexperts.com.br/revoke with client_id and token
(application/x-www-form-urlencoded), or use the connection controls in the panel.
After revocation or invalid_grant, ask the person to reconnect through consent.
Keep tokens out of URLs, logs, chat messages, public files and browser localStorage.