# MYOPL auth.md

Audience: agents reading public MYOPL references, and approved integration
operators connecting a signed MYOPL rules client.

## Public reference access

No registration, account, API key or bearer token is required for public
documentation or the public MCP reference tools. Use
`https://api.myopl.net/mcp` with MCP Streamable HTTP.
Follow the [connection guide](https://myopl.net/ai/integration.md) to initialize
the protocol and discover input schemas. Public access cannot perform account
actions or read private conversations and profiles.

## Personal MCP: OAuth sign-in and scoped permissions

Personal connection: `https://api.myopl.net/mcp/personal`. This is a separate,
consent-based connection for MYOPL Plus and higher plans. Public
ratings and public reference searches remain available without authentication.

1. Read the [protected-resource metadata](https://api.myopl.net/.well-known/oauth-protected-resource/mcp/personal).
2. Discover the [OAuth authorization server](https://api.myopl.net/.well-known/oauth-authorization-server).
   Its issuer is `https://api.myopl.net`; use the advertised authorization,
   token, registration and public JWKS endpoints. This is OAuth 2.0, not an
   OpenID Connect identity service.
3. Use a supported published client identity or dynamic client registration,
   then authorization code with PKCE S256 and the exact registered callback.
   Request only the scopes required for the user's task. End users should not
   need to invent a client ID or paste a password or token into chat.
4. Let the user sign in and approve MYOPL's consent screen. Send the resulting
   access token only as an Authorization Bearer header to the personal endpoint.
5. Use the refresh-token grant at the advertised token endpoint when access
   expires. Store replacement refresh tokens securely. HTTP 429 is a temporary
   limit: wait for Retry-After, then retry; it is not a request to disconnect.
6. The user can remove access in MYOPL Messenger Settings > OPL Intelligence.

| OAuth scope | Permission |
| --- | --- |
| `myopl:rating:read` | Read the consenting player's published OPL ratings. |
| `myopl:sessions:read` | Find the player's league sessions. |
| `myopl:rsvp:write` | Prepare an RSVP for explicit confirmation in MYOPL; preparation does not change attendance. |
| `myopl:statistics:read` | Read the player's own statistics cards; no paid upgrade is required for own statistics. |

The [personal OpenAPI contract](https://myopl.net/openapi-personal.json) declares
the OAuth scheme and operation scopes. Follow the
[connection guide](https://myopl.net/opl-intelligence/connect-your-ai/) for setup.

## Signed A2A registration and provisioning

Supported provisioning method for the separate A2A rules service: manual
approval and provisioning of a MYOPL signing client by the MYOPL operator.
The provisioning request page is [MYOPL Contact](https://myopl.net/contact/).
Select AI, API and Developers and describe the integration. A
contact request does not issue credentials or create an agent account.
Submitting a request sends a message, so an agent must obtain the user's
authorization before submitting it. Do not include secrets in the request.

There is no public automated registration, claim, verified-email, ID-JAG,
anonymous credential issuance, OAuth authorization server or OAuth token
endpoint advertised for this service. Do not invent those URLs or probe
`POST /agent/auth`. MYOPL's ordinary user signup is a separate product flow.

## Credential use

The [A2A card](https://myopl.net/.well-known/agent-card.json) describes the
signed rules service at `https://api.myopl.net/api/v1/agent`, using
JSON-RPC and A2A protocol 0.3 (`message/send`). Requests require
`X-AI-Client-ID`, `X-AI-Timestamp`, `X-AI-Nonce` and `X-AI-Signature` according
to the signing instructions supplied when a client is provisioned. Do not use
these credentials for the public MCP endpoint. Store signing secrets only in
the integration's secret manager, never in browser code or chat.

Sign the exact destination URL, including its query string, and the unchanged
request body. Existing clients moving to `api.myopl.net` must recompute the
signature for the new URL; a signature made for a different host is rejected.
The Cloudflare Worker forwards signed requests to MYOPL's existing rules
service without caching responses or following redirects.

For lost or revoked credentials, contact the MYOPL operator through the same
provisioning request page. No public revocation endpoint or webhook event is
advertised. An anonymous access denial from the signed A2A endpoint is expected;
use public MCP or HTML resources when signed access has not been provisioned.

[Español](https://myopl.net/auth.es.md)