Skip to main content

​
API keys

Parlay uses Stripe-style API keys. Every request carries a Bearer token in the Authorization header. 
Authorization: Bearer pk_sandbox_C4F36IBTB80rkVfp_HVgQIu9GxztHFlbUtpGWfWd1ZV7dtjkR

​
Two environments

Prefix: pk_sandbox_…Sandbox keys hit the same infrastructure as live keys, against test data. AI-cost operations are billed at $0 — use them freely while integrating.Mock recording URLs (mock://perfect-pitch, mock://average-pitch, mock://poor-pitch) return deterministic test analyses in under a second. Use these for unit tests and demos.Base URL: https://parlay-api-dev-o7nogixtqq-uc.a.run.app

​
Key safety

  • Server-side only. Never embed an API key in a mobile app, browser, or anywhere a customer can extract it. Use a thin proxy on your backend instead.
  • One key per environment per service. Don’t share live keys across staging + prod; rotate immediately if leaked.
  • Rotate via the dashboard. Revoking a key is instant — every request after that returns key_revoked.

​
Required headers

HeaderRequired onPurpose
Authorization: Bearer <key>Every requestIdentifies the partner + scopes
Content-Type: application/jsonMutating requests with a bodyStandard JSON body
Idempotency-Key: <uuid>All POST, PATCH, PUT, DELETELets you safely retry on transient failures without duplicate effects

​
Idempotency

Generate a fresh UUID v4 per logical request. Retries with the same key return the cached response. A different key on the same payload creates a duplicate. 
const key = crypto.randomUUID();

await fetch("https://parlay-api-dev-o7nogixtqq-uc.a.run.app/v1/analyses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Idempotency-Key": key,                      // ← same key on retry
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ org_id, rep_id, recording_url }),
});
The MCP server handles idempotency for you — fresh UUID per tool call, automatic.

​
Scopes

Sandbox keys can hit every read + mutate endpoint. Admin operations (creating partners, minting keys, suspending partners) require an admin key — those are not exposed via the MCP server intentionally.

​
Common auth errors

CodeStatusMeaning
authentication_required401Missing or malformed Authorization header
invalid_api_key401Key doesn’t exist or is malformed
key_revoked401Key was revoked via dashboard — rotate to a new one
key_environment_mismatch403Live key used against sandbox URL or vice versa
scope_required403Action requires a scope your key doesn’t have
See the full errors reference for remediation guidance.