# Golem — Agent Registration (auth.md)

Golem registers an agent on behalf of a person and issues a **scoped, short-lived,
revocable** access token. Registration routes through standard OAuth (RFC 7591 / 8414).

## Flows

### Agent-Verified (headless)
Present a workspace key as your machine assertion; receive client credentials for
low-blast-radius scopes (`safety.check`, `context.read`).

    POST https://app.golem.team/oauth/register
    Authorization: Bearer glk_...
    {"name": "my-agent", "scope": "safety.check context.read"}

### User-Claimed (device flow, for write scopes)
Start a device authorization, show the user the `user_code`, and poll the token
endpoint until they approve.

    POST https://app.golem.team/oauth/device        → user_code, device_code, verification_uri
    POST https://app.golem.team/oauth/token          grant_type=urn:ietf:params:oauth:grant-type:device_code

### Instant Trial (keyless, self-expiring)
No key, no wait. Call the device endpoint with ONLY safe scopes (`safety.check`, `context.read`) and an optional `email`; you get client credentials
+ an access token **immediately** (plus the usual `user_code`/`verification_uri`).
Work right away; show the user the `verification_uri` to keep it. If nobody approves
within 24h the trial workspace is disabled.

    POST https://app.golem.team/oauth/device
    {"name": "my-agent", "scope": "safety.check context.read", "email": "you@example.com"}
    → access_token (use now) + client_id/client_secret + user_code + verification_uri

## Token exchange (client_credentials)

    POST https://app.golem.team/oauth/token
    {"grant_type": "client_credentials", "client_id": "gac_...", "client_secret": "gla_..."}

Returns a Bearer JWS (≤5m) carrying your granted `scope`. Metadata: https://app.golem.team/.well-known/oauth-authorization-server

## Scopes

| scope | grants |
|-------|--------|
| `safety.check` | URL / tool-target threat verdicts |
| `context.read` | search + read the acting user's own conversations & artifacts |
| `artifact.read` | fetch artifact bodies from the ledger (user-claimed) |
| `flags.write` | raise / resolve behavior flags (user-claimed) |