# Glowcrumb agent registration Glowcrumb records website sessions through a customer's verified HTTPS collection hostname. Use this guide to request a new project and obtain project-scoped API access on behalf of its owner. Human sign-in is provided by Clerk. ## Discover - Protected resource: https://glowcrumb.com/.well-known/oauth-protected-resource - Authorization server: https://glowcrumb.com/.well-known/oauth-authorization-server - Resource and issuer: https://glowcrumb.com Read the metadata for authoritative endpoint URLs. This environment only supports WorkOS auth.md's user-claimed `service_auth` flow. No anonymous access, ID-JAG from external providers, OAuth client registration, or automatic identity linking. This is a registration API, not an MCP server. ## Register First ask the owner for the email they use for Glowcrumb, the exact HTTPS website origin, and the collection subdomain they control. Ask permission before requesting access. The email is a login hint, never proof of ownership. POST https://glowcrumb.com/agent/identity (the identity endpoint) as application/json: ```json { "type": "service_auth", "login_hint": "owner@example.com", "client_name": "My coding agent", "project": { "name": "My website", "origin": "https://example.com", "hostname": "crumbs.example.com" }, "scope": "projects:read projects:write" } ``` The project and client_name fields are Glowcrumb-specific. A new project is created only after approval. If the exact hostname and website origin already belong to the approving owner, approval reconnects that project. It cannot take over another account’s project or hostname. The owner may have at most 10 projects. Registration returns a private claim_token and claim containing user_code, verification_uri, expires_in, and interval. Give the owner the verification_uri and six-digit user_code. They sign in with a matching verified email, check the project and permissions, type the code, and approve or deny. Do not approve your own request or automate the human confirmation. Never expose claim_token to the browser, send it to another service, or log it. The request expires after 10 minutes. To recover from expiry, register again and ask the owner to approve the new request. There is no separate claim renewal endpoint. ## Exchange the claim Poll the token_endpoint with application/x-www-form-urlencoded parameters: ```text grant_type=urn:workos:agent-auth:grant-type:claim&claim_token= ``` Wait at least claim.interval seconds between calls. On authorization_pending keep waiting. On slow_down add five seconds to your interval for subsequent requests. Stop on access_denied, expired_token, or invalid_grant. Bound polling to the claim's expiry. On rate_limited (HTTP 429), honor Retry-After. Approval returns access_token, token_type, expires_in, scope, project_id, identity_assertion and assertion_expires. Keep both credentials in secure local storage. Access tokens last at most one hour; authorization lasts 30 days. ## Use the API Send Authorization: Bearer to this resource only. - GET https://glowcrumb.com/api/projects — the single approved project. - GET https://glowcrumb.com/api/projects//install — project status, DNS records, automatic-recording script, and optional consent-required script. - POST https://glowcrumb.com/api/projects//domains/verify — check DNS and HTTPS. Add the TXT ownership record and DNS-only CNAME returned by /install. Collection remains inactive until real ownership and HTTPS checks pass. Dev and previews do not provision production certificates. Honor the site's consent requirements; use consentScript where approval must precede recording. Never weaken masking. Scopes: - projects:read (required): read this project's installation and DNS details. - projects:write (optional, default): request its domain ownership/TLS checks. - sessions:read (optional, never default): read this project's session list, session replay, summary, journeys, and existing insights. Request this only when the owner wants the agent to inspect recordings. With sessions:read, GET /api/projects//sessions, /sessions/, /summary, /journey?userId=, and /insights are available. All paths are relative to the resource above. Agents cannot change privacy or AI settings, trigger paid analysis, delete data, create more projects, or manage grants. ## Renew and revoke Before token expiry, exchange identity_assertion at the same token_endpoint: ```text grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion= ``` Form-encode the assertion. There is no refresh token. Use one token until it is near expiry; do not mint on every API call. A grant permits at most 20 live access tokens and 10 token issuances per minute. Its API limit is 120 calls per minute. POST application/x-www-form-urlencoded token= to revocation_endpoint to revoke that token. This does not revoke the assertion. The owner can revoke the entire authorization at https://glowcrumb.com/agent/access, immediately preventing API access and renewal. Deleting the project also removes access. After invalid_grant, stop and request new human authorization; never repeatedly register without permission. ## Errors and credential handling Token/registration errors use OAuth error and error_description. API errors use error with a readable explanation: 401 means invalid/expired/revoked credentials; 403 means missing permission; 404 means unavailable project. Never try a different project identifier to bypass a refusal. Discovery appears in WWW-Authenticate on protected API responses. Keep assertions, bearer tokens, claim tokens and approval links out of commits, logs, screenshots and recordings. No API keys, passwords or Clerk secrets are needed from the owner. This guide authorizes no billing or destructive actions.