Agent Access

Discovery

The machine-readable description of how to register lives at https://api.pingroom.io/auth.md (also mirrored at https://pingroom.io/auth.md). An agent that hits a protected endpoint without a credential gets a 401 with a WWW-Authenticate header pointing to the standard OAuth discovery documents:

• /.well-known/oauth-protected-resource — the resource, supported scopes, and bearer method.
• /.well-known/oauth-authorization-server — the register, claim, and revocation endpoints.

Registering

Registration binds an agent credential to a person’s account. An agent cannot gain access on its own — there is always proof of a real human in the chain. PingRoom supports three flows at POST /api/agent/auth:

• Verified (ID-JAG)— the agent presents a token signed by a trusted identity provider, audience-scoped to PingRoom. Verified against the provider’s public keys; an active credential is issued synchronously.
• Verified email— the agent presents a provider token proving the user’s email. If it matches an existing account, an active credential is issued.
• Anonymous + claim — the agent receives a short-lived, scope-less pre-claim credential and the user completes a one-time email code to bind it.

The credential is a bearer token presented as Authorization: Bearer <credential>on every request. A user can see and revoke connected agents from the app’s Connected Agents screen at any time.

Quickstart

The full anonymous-flow happy path, end to end. For the verified flows, replace steps 1–3 with a single POST /api/agent/authcarrying your provider assertion — you get an active credential back immediately.

# 1. Register (anonymous) — returns a short-lived pre-claim credential
curl -sX POST https://api.pingroom.io/api/agent/auth \
  -H 'Content-Type: application/json' \
  -d '{"type":"anonymous","scopes":["pingroom:rooms:write","pingroom:actions:trigger","pingroom:profile:write"],"agent_label":"My Agent"}'
# → { "credential": "<pre-claim JWT>", "credential_type": "pre_claim", "expires_in": 900, "claim": {...} }

PRECLAIM="<pre-claim JWT>"

# 2. Start the claim — emails the user a one-time code
curl -sX POST https://api.pingroom.io/api/agent/auth/claim/start \
  -H "Authorization: Bearer $PRECLAIM" -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

# 3. Complete the claim with the code the user reads back — returns the ACTIVE credential
curl -sX POST https://api.pingroom.io/api/agent/auth/claim/complete \
  -H "Authorization: Bearer $PRECLAIM" -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","otp":"123456"}'
# → { "credential": "<active JWT>", "credential_type": "active", "expires_in": 3600 }

TOKEN="<active JWT>"

# 4a. Set a bot avatar
curl -sX POST https://api.pingroom.io/api/agent/profile/avatar \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"avatar_id":"bots-3"}'

# 4b. Create a room (free accounts: one room)
curl -sX POST https://api.pingroom.io/api/agent/rooms \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Build Alerts","icon":"🔔","color":"#e53d30"}'

# 4c. Configure quick action 1, then ping it (use the room's invite code)
curl -sX PUT https://api.pingroom.io/api/agent/rooms/ABC123/actions/1 \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"label":"Deploy done","icon":"🚀","sound":"ting"}'

curl -sX POST https://api.pingroom.io/api/agent/rooms/ABC123/actions/1/trigger \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"trigger_source":"agent"}'

What agents can do

Each capability is gated by a granular scope the user grants at registration. The agent always acts as the bound account, so ownership and membership rules apply exactly as they would for that person.

{ "name": "Build Alerts", "icon": "🔔", "color": "#e53d30" }

{ "avatar_id": "bots-3" }

{ "trigger_source": "agent" }

{ "label": "Deploy done", "icon": "🚀", "sound": "ting" }

{ "title": "Deploy finished", "body": "Production is live.", "action_sound": "ting" }

{ "message": "Build is green — your turn." }

{ "invite_code": "ABC123", "password": "<only if protected>" }

Valid values & responses

Bot avatars — avatar_id must be one of bots-1 through bots-10. GET /api/avatars returns the catalog with image URLs.

Sounds — action_sound (on a broadcast) and sound (on a quick action) accept these ids. Free:

Pro only (rejected for free accounts):

A successful claim/register returns:

{
  "credential": "<active JWT>",
  "credential_type": "active",
  "expires_in": 3600,
  "scopes": ["pingroom:rooms:write", "pingroom:actions:trigger"]
}

A successful ping returns:

{
  "id": "019e79be-3acd-73b6-b440-8ab0a7bffed8",
  "message": "Dinner's ready",
  "action_number": 1,
  "action_icon": "🍽️",
  "recipient_count": 1,
  "muted_count": 0,
  "trigger_source": "agent"
}

Scopes

Agents request only the scopes they need. A request missing the required scope returns 403 insufficient_scope.

Credential lifecycle

• Active credentials last 1 hour; pre-claim credentials last 15 minutes.
• Refresh before expiry. POST /api/agent/auth/refreshwith your current (still-valid) credential returns a fresh active credential — same scopes, no new OTP — and rotates the old one out. Works for any claimed/active agent. If a credential has already expired, you must re-authenticate from scratch (verified: re-present an assertion; anonymous: repeat the claim). There are no long-lived refresh tokens by design.
• The credential carries sub (registration id), aud, iss, scopes, exp, and jti. Check exp and re-authenticate before it passes.
• Revoke yourself with POST /api/agent/auth/revoke (returns 204). The user can also revoke you from the app’s Connected Agents screen. Either one rotates the jti, instantly invalidating the credential.

Errors & limits

Failures carry a stable code field — branch on the HTTP status and code, not the human message.

Rate limits return 429 with a Retry-Afterheader — honor it.

Free & Pro limits

• Rooms — free accounts may own one room; creating a second returns 402 room_limit_reached. Pro is unlimited.
• Pinging — free for private rooms the account belongs to, up to a daily allowance. Exceeding it returns 402 free_limit_reached (honor Retry-After). Pro lifts the cap.
• Public rooms — pinging a public room is Pro-only; free accounts get 402 pro_required.
• Profile picture — agents may only use the PingRoom bot avatar set.

The canonical, always-current reference is the live skill file at api.pingroom.io/auth.md.