# Auth.md — Guth owner-claimed agent access

Guth lets an existing account holder authorize an agent to read the public field-guide catalog. This service supports service_auth (owner-claimed registration) and the separate existing OAuth code/S256 flow. Registration without an owner email, incoming provider identity assertions, public account signup, notebook provisioning, mailbox provisioning, and email-code delivery are not supported.

## Discovery and scope

Issuer: https://guthlabs.ai
Authorization-server metadata: https://guthlabs.ai/.well-known/oauth-authorization-server
Resource: https://guthlabs.ai/agent-api/guides
Canonical protected-resource metadata: https://guthlabs.ai/.well-known/oauth-protected-resource/agent-api/guides
Service assertion public keys: https://guthlabs.ai/agent/identity/jwks
Scope: public.guides.read — read the public field-guide catalog; no private account data or writes.

## Register and ask the owner to claim

POST https://guthlabs.ai/agent/identity with Content-Type application/json:

    {"type":"service_auth","login_hint":"owner@example.com"}

The response contains registration_id, registration_type, claim_token, claim_token_expires, post_claim_scopes, and claim {user_code, expires_in, verification_uri, interval}. Registration gives no access token or identity_assertion. The owner email must belong to an existing Guth account; the registration response does not reveal whether the account exists.

Show the owner the returned verification_uri and six-digit user_code. The owner signs into Guth, confirms the requested permission, types the code, and approves. Do not automate the human approval, put the code into the URL, ask for the owner's password, or expose the claim_token to the browser. Codes and claim handles expire after ten minutes; five wrong code attempts lock the registration. Only the signed-in account whose confirmed email matches login_hint may claim it.

Poll POST https://guthlabs.ai/oauth/token with application/x-www-form-urlencoded no more often than every five seconds:

    grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=RETURNED_CLAIM_TOKEN&resource=https%3A%2F%2Fguthlabs.ai%2Fagent-api%2Fguides

authorization_pending means the owner has not finished. slow_down means wait longer. expired_token means start a new registration. A successful claim-grant response contains access_token, token_type Bearer, expires_in, scope, identity_assertion, and assertion_expires. The service assertion is issued only after human claim.

## Use and renew

Send Authorization: Bearer ACCESS_TOKEN only to GET https://guthlabs.ai/agent-api/guides. Tokens last at most900 seconds and never beyond the registration's lifetime. The registration and reusable service assertion last at most one hour after the owner claim. No refresh tokens are issued.

Before assertion expiry, re-exchange the same service assertion at POST https://guthlabs.ai/oauth/token:

    grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=RETURNED_IDENTITY_ASSERTION&resource=https%3A%2F%2Fguthlabs.ai%2Fagent-api%2Fguides

This returns a new access token. It does not extend the registration or assertion lifetime. Unexpired tokens per registration are limited to32. Every registration token is checked against live registration state before use; revocation or expiry denies access even if provider token storage has not yet propagated.

## Revoke and manage

An agent can revoke one access token at POST https://guthlabs.ai/oauth/token using application/x-www-form-urlencoded with token=ACCESS_TOKEN and optional token_type_hint=access_token. If client_id is supplied it must match the token's issuing client. Unknown/already-revoked tokens return200. Revoking one token leaves the service assertion usable until registration expiry or owner revocation.

The owner can open https://guthlabs.ai/agent/registration?registration=REGISTRATION_ID while signed into the claiming account to inspect or revoke that registration. Owner revocation invalidates every token and service assertion for it. This is a direct registration management page, not a claim that Guth already provides an account-wide registration list.

The separate browser OAuth flow still supports /oauth/register client registration and /oauth/authorize with S256 PKCE for public.guides.read; OAuth client registration is distinct from the service_auth registration above. The service_auth flow keeps the legacy https://guthlabs.ai/agent-api/guides audience. Browser OAuth accepts the explicit site-root resource https://guthlabs.ai; omitting resource continues to select the legacy audience. Both audiences authorize only the public guide endpoint and public.guides.read. These endpoints do not grant other Guth product capabilities.
