All pages
Authentication
Three mechanisms handle authentication, each for one job. None of them ever exposes a craving user’s credentials to your app.
Request signatures (craving to you)
Every request craving sends to your servers (webhooks, chat tool invokes, drawn block content_url fetches and action_url votes, outbound channel sends, and review dry runs) carries an HMAC-SHA256 signature header:
X-Craving-Signature: t=1757793600,v1=<hex hmac-sha256(secret, "<t>.<raw body>")>
X-Craving-Event: installation.createdsecret is your webhook signing secret (whsec_…). Verify the signature against the raw request body before parsing JSON, reject timestamps older than 5 minutes (300 seconds), and compare digests in constant time.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyCraving(rawBody: string, header: string | null, secret: string): boolean {
if (!header) return false;
const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
const ts = Number(parts.t);
if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
const a = Buffer.from(parts.v1 ?? '', 'utf8');
const b = Buffer.from(expected, 'utf8');
return a.length === b.length && timingSafeEqual(a, b);
}import hashlib
import hmac
import time
def verify_craving(raw_body: bytes, header: str | None, secret: str) -> bool:
if not header:
return False
parts = dict(p.strip().split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
expected = hmac.new(
secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))Inbound channel events you POST to gc_app_channel_event use the exact same X-Craving-Signature format, signed by your server with the same webhook secret.
Installer sessions (your iframes)
Framed Home blocks and embedded dashboards open with the session token in the URL fragment (never in the query string): https://your-url#craving_session=<jwt>&theme=dark&block=<block_id>. The JWT is signed with ES256. Verify it against our public JWKS:
GET https://api.craving.com/functions/v1/gc_marketplace_api/.well-known/jwks.jsonDecoded claims:
{
"iss": "https://craving.com/marketplace",
"sub": "<installation_id>",
"aud": ["https://app.example.com"],
"exp": 1757794500,
"jti": "…",
"scope": "block",
"installation_id": "…",
"app_id": "…",
"installer": { "id": "…", "username": "sophie", "name": "Sophie", "avatar": "…" },
"block_id": "…",
"landing_id": "…",
"settings": { "title": "My shelf", "layout": "grid" }
}scope is "block" on a public Home (15-minute lifetime; the Visitor is anonymous to your app) or "dashboard" on the installer’s app page (60-minute lifetime). Verify that aud contains your origin and iss equals "https://craving.com/marketplace". Key your state by installation_id.
Install tokens (you to craving)
Exchange the one-time install_code from installation.created at the token endpoint using HTTP Basic auth (or client_id and client_secret in the JSON or form body):
POST https://api.craving.com/functions/v1/gc_marketplace_oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
grant_type=install_code&install_code=<code from the webhook>{
"access_token": "crvat_…",
"refresh_token": "crvrt_…",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "profile.read chat.tools",
"installation_id": "…"
}Access tokens expire after 1 hour (3600 seconds). Exchange a refresh token with grant_type=refresh_token&refresh_token=…. Every refresh rotates both tokens and revokes the old refresh token immediately. Replaying a rotated refresh token returns invalid_grant; if a fresh token of yours ever fails with invalid_grant, treat it as a leak and rotate your client secret. Uninstalling revokes every token for that installation.
Token errors follow RFC 6749: invalid_client (401), invalid_grant, invalid_request, unsupported_grant_type and installation_inactive (400). The token endpoint is rate limited per client id and per IP (Rate limits).
Connecting your app to other platforms
External OAuth flows (such as Calendly, Discord or Shopify) run on your own servers. Store external tokens on your side keyed by installation_id, then call PATCH /v1/installations/{id} with connections (requires profile.read) so the installer sees a “Connected” badge on craving.