# wcway authentication (auth.md)

Public REST reads (https://wcway.com/api/v1) and the public MCP server (https://wcway.com/mcp) need no account and no API key.
The protected MCP endpoint https://wcway.com/mcp/account uses OAuth with the existing wcway passkey login.

## Discover

Read https://wcway.com/.well-known/oauth-protected-resource.

- `resource` is https://wcway.com.
- `authorization_servers` is empty for public toilet search.
- `bearer_methods_supported` is empty for public toilet search.

For account access, read https://wcway.com/.well-known/oauth-protected-resource/mcp/account and https://wcway.com/.well-known/oauth-authorization-server.
Register a public client at https://wcway.com/oauth/register. Use authorization code with PKCE S256 and scope `account:events`.
The signed-in account approves read access to its partner claims, billing state and profiles. The public REST read operations remain keyless.
The OpenAPI document declares `security: []` at the top level. The read operations name no security scheme. An operation that needs a credential names its scheme.

The MCP server card declares `authentication.type: "none"`.

## Pick a method

Use MCP (Streamable HTTP, JSON-RPC 2.0) at https://wcway.com/mcp, or use REST under https://wcway.com/api/v1.
Send no Authorization header, API key or cookie.

## Use

```http
GET /api/v1/toilets/nearest?lat=49.8728&lon=8.6512&limit=5 HTTP/1.1
Host: wcway.com
Accept: application/json
```

The limit is 60 requests per minute per IP. The map area endpoint `GET /api/v1/toilets` has its own limit of 300. The `RateLimit` headers show the state.

## Errors

REST errors use `application/problem+json` with `type`, `title`, `status` and `detail`. Some add `invalid_params` or `retry_after_seconds`.
MCP uses JSON-RPC errors for protocol faults and `isError` results for tool faults.

- 429: wait for `Retry-After`, then send the request again.
- 503: the database is busy for a moment. Wait for `Retry-After`, then send the request again.
- 400: read `invalid_params` and correct the request.

## Revocation

Public search needs no credentials. Users revoke account connections at https://wcway.com/oauth/connections.
Clients can revoke account credentials at https://wcway.com/oauth/revoke. Account deletion revokes all grants.

## Account Events

Use MCP version `2026-07-28` on https://wcway.com/mcp/account with the access token in the Authorization header.
The public MCP endpoint never advertises Events. Account Events appear only while the verified relay is ready.
`partner.claim.status_changed` reports changes to your own claim status.
`partner.profile.updated` reports changes to your own profile conditions, hours and temporary closure.
Filter by `listing_id` or `toilet_id`. Event data does not grant permission to change an account.
Subscriptions expire within 24 hours and have no replay. Refresh before the returned `refreshBefore` time.
Use `get_my_partner_listings` to read your current listings.