Pepper.

1 Issue a key pair

Creates a client_key (pk_live_…, public) + client_secret (sk_live_…, shown ONCE) for your workspace.

curl -X POST "$PEPPERBOARD/api/agent/keys/v2" \
  -b "pb_session=$PB_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name":"My agent","scopes":["board:read","instructions:write","videos:write","ideas:write","webhooks:write","media:read"]}'

Runs with your dashboard session: -b sends the pb_session cookie — copy its value from your browser's DevTools (Application → Cookies) while logged in. Save $CLIENT_KEY and $CLIENT_SECRET from the response now; the secret is never shown again (rotate the key if you lose it).

2 Exchange the pair for a token

Trades the key pair for a Bearer access token — save it as $TOKEN.

curl -X POST "$PEPPERBOARD/api/v1/auth/token" \
  -H "X-Client-Key: $CLIENT_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"client_secret\":\"$CLIENT_SECRET\"}"

The client_key goes in the X-Client-Key header; the secret travels only here, in the JSON body — never as a Bearer token, never in a URL. Response: {"access_token":"…","token_type":"Bearer","expires_in":3600,"scopes":[…]}.

3 Post an idea card

Submits a new channel idea — a card on the idea-first board — to your workspace.

curl -X POST "$PEPPERBOARD/api/v1/ideas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Rainbow Giggles: a 2-minute lullaby episode about a sleepy moon"}'

Any /api/v1 write works the same way: Authorization: Bearer $TOKEN plus a JSON body. Send an Idempotency-Key header on every mutation; replays within 24h return the original response.

4 Poll the agent inbox

Drains unclaimed Muse-inbox events, oldest first — take the first event's id for step 5.

curl -s "$PEPPERBOARD/api/v1/inbox?limit=50" \
  -H "Authorization: Bearer $TOKEN"

Each event row carries id, event, payload, and a pre-computed signature (same HMAC scheme as step 6, over the JSON payload).

5 Claim it, do the work, mark it handled

Claims the event so no other worker grabs it, then marks it handled when the work is done.

export EVENT_ID="paste-an-id-from-step-4"
curl -X POST "$PEPPERBOARD/api/v1/inbox/claim" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"ids\":[\"$EVENT_ID\"]}"
# …do the work the event asks for…
curl -X POST "$PEPPERBOARD/api/v1/inbox/$EVENT_ID/handled" \
  -H "Authorization: Bearer $TOKEN"

Claiming sets claimed_at; handling sets handled_at. If your worker crashes between the two, the event is safe to re-claim.

6 Verify a webhook signature

Checks the X-Pepperboard-Signature header on incoming webhooks.

const crypto = require('node:crypto');            // inside your webhook handler
const expected = 'sha256=' +
  crypto.createHmac('sha256', WEBHOOK_SECRET)     // your endpoint's webhook secret
    .update(rawBody)                              // the EXACT request bytes, before JSON.parse
    .digest('hex');                               // lowercase hex, prefixed with "sha256="
const ok = sig.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)); // constant-time compare

The scheme is exactly what the server signs with: sha256= + lowercase hex HMAC-SHA256 of the raw request body, keyed with your endpoint's webhook secret. Webhooks also carry X-Pepperboard-Event and X-Pepperboard-Delivery headers. Reject and report on mismatch.

7 Rate limits & token lifetime

Know the budgets before you script a loop — and re-exchange before the token dies.

Tokens live 1 hour (expires_in: 3600) — re-run step 2 before expiry. Rotation or revocation kills outstanding tokens on their very next request: the key row is re-read on every call, so there is nothing to flush. Defaults come from V1_RATE_LIMIT_PER_5MIN / TOKEN_RATE_LIMIT_PER_MIN on the server.