# auth.md — Chexlow

Chexlow is a public product and price-comparison catalog. Discover → register with an email login hint → obtain the user's explicit approval on this service → poll → exchange the service-signed identity assertion → read the catalog.

Public product searches, product details, and categories are readable without authentication. OAuth is optional; anonymous public catalog access is not anonymous agent registration. A supplied bearer token must be valid: invalid, expired, or revoked tokens are rejected, never silently treated as anonymous.

## Step 1 — Discover the supported profile

- Canonical issuer and resource: https://chexlow.com
- Protected Resource Metadata (machine-readable resource discovery): https://chexlow.com/.well-known/oauth-protected-resource
- Authorization Server metadata (endpoints and supported grants): https://chexlow.com/.well-known/oauth-authorization-server
- Agent identity registration: https://chexlow.com/agent/identity
- Claim renewal: https://chexlow.com/agent/identity/claim
- Service-owned browser login and consent: https://chexlow.com/agent/claim
- Token exchange and claim polling: https://chexlow.com/oauth/token
- Credential revocation: https://chexlow.com/oauth/revoke
- Public signing keys: https://chexlow.com/oauth/jwks
- API reference and integration limits: https://chexlow.com/developers

This implements the WorkOS auth.md v0.6 service_auth entrypoint and the v0.4/v0.5 verified_email registration shape. Follow the metadata-defined URLs, not assumed /oauth2 paths. The current identity_endpoint and claim_endpoint remain available; register_uri and claim_uri provide older discovery names for the supported browser-approval flow. See [Supported older agents](#supported-older-agents) before using an earlier request shape.

Only catalog:read is available: read the public comparison catalog, including product details, visible offers, and categories. No private customer data, account management, admin, checkout, payment, raw feed, or outbound click permission is granted. This flow does not create API keys, normal application/admin credentials, or user accounts, and does not enroll a paid plan. Product prices are retailer offers, not an API subscription quote. See [integration documentation](https://chexlow.com/developers), [terms](https://chexlow.com/terms), [privacy](https://chexlow.com/privacy), and [integration contact](https://chexlow.com/contact).

## Step 2 — Register using service_auth

First tell the user the service name and catalog:read scope, and obtain permission to submit their email as login_hint. POST application/json to the identity_endpoint:

```json
{"type":"service_auth","login_hint":"user@example.com"}
```

The response contains registration_id, registration_type: "service_auth", claim_url, an opaque claim_token, claim_token_expires (ISO timestamp), post_claim_scopes: ["catalog:read"], and claim: {user_code, expires_in, verification_uri, interval}. user_code is exactly six digits; expires_in is 600 seconds and interval starts at 5 seconds. The verification_uri is a same-service /agent/claim URL containing a claim_attempt_token, not the user_code.

There is NO identity_assertion, access_token, client secret, or other useful API credential before approval. login_hint does not prove identity or silently link an account. The user must already have an account and prove its password on the service-owned page; the signed-in email must match the registration's email exactly under the service's email normalization. No signup, email delivery, email verification message, or external identity-provider request occurs.

Registrations expire after 3600 seconds and are bounded to 1000 live registrations per site. Treat claim_token and the verification URI as secrets. claim_token is returned once; keep it only for this ceremony, never in URLs or logs. The service stores hashes of claim_token, claim_attempt_token, and user_code. Anonymous pre-claim registration, provider ID-JAG registration, and provider SET/events are not supported.

## Step 3 — Hand the ceremony to the user

Show claim.verification_uri and claim.user_code together. Ask the user to open that link, enter the code on the service-owned page, sign in with the existing account, and explicitly approve catalog:read (or deny). Never ask for the account password or have the user send the code back to the agent.

GET /agent/claim renders the service's login/consent page. Its browser form POSTs to /agent/claim; /agent/identity/claim/complete is the equivalent service-owned form action, not an agent approval API. The page uses a secure CSRF cookie and verifies the attempt, code, password, exact registration/email binding, and explicit consent before completing the claim. A code alone cannot authorize a different account.

For a code that has expired while its registration remains active, POST application/json to claim_endpoint with the original claim_token and the same email:

```json
{"claim_token":"<claim_token>","email":"user@example.com"}
```

The response contains registration_id, claim_attempt_id, status: "initiated", expires_at, and a fresh claim_attempt block with user_code, expires_in, verification_uri, and interval. Surface the new code and URL; the old attempt URL/code stops working. At most five renewals are allowed. An already active or completed ceremony returns claimed_or_in_flight; a different email is rejected, never rebound. On claim_expired start a new service_auth registration.

## Step 4 — Poll for approval

POST application/x-www-form-urlencoded to https://chexlow.com/oauth/token:

```text
grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>
```

Wait at least claim.interval seconds between polls. authorization_pending means wait for the user. slow_down means add at least 5 seconds to the interval before the next poll. expired_token means the ceremony or registration expired: renew the code only while the registration remains active, otherwise register again. access_denied means stop; do not override the user's denial.

After approval the token response contains access_token, token_type: "Bearer", expires_in: 900, scope: "catalog:read", identity_assertion, and assertion_expires (ISO timestamp). This is the first credential issuance. Successful delivery atomically consumes the claim-token polling capability; use the returned assertion for subsequent exchanges, not the claim grant. Keep identity_assertion securely and discard the claim_token. The assertion lasts at most 3600 seconds and never outlives its registration.

## Step 5 — Exchange the service-signed assertion and use the token

POST application/x-www-form-urlencoded to the token_endpoint. Percent-encode all actual form values:

```text
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>&resource=https://chexlow.com
```

resource is required and must exactly equal https://chexlow.com. The service verifies its own oauth-id-jag+jwt assertion, canonical issuer, token-endpoint audience (https://chexlow.com/oauth/token), lifetime, registration, and granted scope. This assertion's audience differs from the access token's resource audience. This service-signed assertion is not an externally supplied provider ID-JAG. The response contains access_token, token_type: "Bearer", expires_in: 900, and scope: "catalog:read". No refresh_token is issued; reuse the assertion until its expiry. invalid_grant means discard it and restart registration/consent.

Send access tokens only as Authorization: Bearer headers, never URL parameters. Tokens are site-specific EdDSA JWTs with typ=at+jwt, agent_access purpose, canonical issuer/resource, and catalog:read only. Every authenticated catalog request checks the active grant in shared Redis, including its live claim registration when applicable. On a previously working token's 401, try the current assertion once; if that also fails, restart discovery and consent.

## Step 6 — Revoke

POST application/x-www-form-urlencoded to https://chexlow.com/oauth/revoke with token=<access_token>&token_type_hint=access_token. A claim-issued token needs no client_id. Revocation returns HTTP 200 idempotently, including unknown tokens, and affects the next authenticated catalog request. Access-token revocation does not invalidate the identity_assertion; a valid assertion can mint a new token.

To revoke the claimed registration and all its derived access, submit token=<identity_assertion>&token_type_hint=identity_assertion to the same endpoint. This is a service-supported registration revocation hint, not a provider event endpoint.

## Supported older agents

Older discovery clients may use agent_auth.register_uri (https://chexlow.com/agent/auth) and agent_auth.claim_uri (https://chexlow.com/agent/auth/claim). These are real entrypoints to the same site-bound registration and claim-renewal operations as identity_endpoint and claim_endpoint.

The WorkOS auth.md v0.4/v0.5 email registration request is supported at either registration entrypoint:

```json
{"type":"identity_assertion","assertion_type":"verified_email","assertion":"user@example.com"}
```

Its response uses registration_type: "email-verification" and the same claim_token, claim and post_claim_scopes fields described above. There is still no credential before approval. In this older shape, verified_email names a service-verified email flow; the supplied email is not proof of identity. Follow Steps 3–6 unchanged: show the verification_uri and user_code to the user, require the user's existing account and explicit approval in the service-owned browser page, poll the advertised token_endpoint, exchange the assertion and revoke as needed.

The compatibility scope is v0.4/v0.5 browser approval, not the pre-v0.4 mailed-OTP ceremony. No email is sent, no API key is issued, and JSON OTP submission by an agent cannot complete a claim. Do not send requested_credential_type, credential_type, scopes, mixed login_hint/assertion fields, provider ID-JAGs, or anonymous registration requests. Only catalog:read access tokens are available after consent.

## Alternative — OAuth authorization code with S256

The separate public OAuth client flow remains supported. POST application/json to https://chexlow.com/oauth/register with redirect_uris (one to ten exact HTTPS URLs, or literal loopback HTTP URLs), token_endpoint_auth_method: "none", grant_types: ["authorization_code"], response_types: ["code"], and optionally client_name. Registration lasts 30 days; no client secret or dynamic registration management endpoint exists. Redirect URLs must not contain credentials, fragments, wildcards, or existing code, error, state, or iss query parameters.

Open https://chexlow.com/oauth/authorize in the user's browser with response_type=code, client_id, the exact registered redirect_uri, scope=catalog:read, resource=https://chexlow.com, cryptographically random state, code_challenge, and code_challenge_method=S256. S256 is BASE64URL(SHA256(code_verifier)); use a fresh 43–128 character verifier for each request. Existing account email/password verification and explicit approval occur only on the service's authorization page. Clients must never collect passwords.

The callback contains code, state, and iss. Verify state and require iss=https://chexlow.com. Errors redirect only after validating the client and redirect URI. Codes expire after 120 seconds and are single-use, bound to client, exact redirect URI, resource, scope, and S256 verifier. Reusing an issued code revokes its associated token.

Exchange form-encoded grant_type=authorization_code, client_id, redirect_uri, resource=https://chexlow.com, code, and code_verifier at the token_endpoint for a 900-second catalog:read bearer. Revoke this flow's token with client_id and token at the revocation_endpoint.

## Errors and operational constraints

JSON errors use error and error_description; do not treat failures as successful registration or consent. invalid_request means fix the body; unsupported_identity_type means use service_auth or the documented verified_email request, not anonymous or provider assertions. invalid_claim_token means restart registration; claim_email_mismatch means stop and correct the intended account, never silently switch accounts; claim_expired means the registration closed; claimed_or_in_flight means do not restart an active/completed attempt.

At the token endpoint, authorization_pending, slow_down, expired_token, and access_denied govern polling as above. invalid_grant rejects invalid/expired assertions or codes; invalid_target rejects a noncanonical resource; invalid_scope rejects permissions beyond catalog:read; unsupported_grant_type rejects unsupported grants. On temporary 5xx failures, back off rather than bypassing approval or assuming anonymous authorization.

No implicit, password, client-credentials, refresh-token, standard device_code, or OpenID Connect grant is supported. The password entered by the human on the service-owned page is not an OAuth password grant. No provider trust list, provider ID-JAG registration, SET receiver, or events_supported capability is advertised.

Registration, consent, codes, assertions, and active grants require initialized shared Redis; outages fail closed. Signing uses site- and purpose-separated HKDF-SHA256 Ed25519 material derived from the protected server refresh secret; private keys never leave the API. Pods must share that protected configuration. Rotating it changes the public key and immediately invalidates outstanding tokens/assertions; there is no overlapping old-key window. Redelegate after rotation or expiry.
