Sorb™ Cloud REST API

When you finish this page you know every customer-facing route on app.sorbcloud.com, what it needs to authenticate, and what it does. You need a Sorb account for anything beyond plugin pairing; most routes also accept a project API key, so CI and agent callers never need a browser session.

All paths are relative to https://app.sorbcloud.com. Every response is JSON; errors are { "error": "<code>", "message"?: "<string>" } with a 4xx/5xx status — the error code is stable, the message is for humans.

This page lists only the customer-touched surface. It omits internal routes (admin/*, ai/*, billing/*, webhooks, dev/*, e2e-hooks/*, sensor/ingest, render/*, feed/*, waitlist, support, onboarding/*) and the OAuth connector routes (connectors/*), which are covered as a sentence in the plugin and cloud guides rather than as a REST reference.

Auth models

Most routes accept either a session or a project key — the tables below mark those session or key. A publishable key (sorb_pk_…) is read-scoped on this API: it can call reads, and the one deliberate exception below. A secret key is required for everything else that writes. Routes marked (sk) need a secret key when called by key; a session is always read-write (route-level role checks, where noted, still apply on top).

Publishable keys are meant to be embedded in a client — the plugin and the React SDK both boot with one. Never embed a secret key in anything that ships to a browser or device.

Plugin pairing & publish

The Figma plugin (Canopy) has no browser session, so it authenticates by a short-lived pairing code instead — see Connect flows for the user-facing walkthrough.

Projects

token-pr, tokenize, and both preview-mint routes require the approve_merge org role when called from a session (a key's write scope is its own authorization).

Token sets

A token set is a named, versioned collection of resolved tokens. head, diff and versions* are reads and free of any entitlement gate.

Keys

Key management is dashboard-session-only — a key can't be used to mint, rotate, or revoke keys.

Orgs

The full allowlist backing these tables is committed as www/app/docs/cloud/_routes.js in this site's source, alongside a comment listing every route family this reference deliberately omits.

One request per auth model

Public + code — a plugin pairs without ever holding a credential:

curl -X POST https://app.sorbcloud.com/api/plugin-connect/start \
  -H "content-type: application/json" \
  -d '{"code":"<a-high-entropy-code-you-generate>"}'
# -> {"status":"pending"}

curl "https://app.sorbcloud.com/api/plugin-connect/poll?code=<the-same-code>"
# -> {"status":"pending"} while you wait, then once:
# -> {"status":"ready","bridgeUrl":"...","apiKey":"sorb_pk_...","orgId":"..."}

Bearer project key — publish a token set from a script or CI job:

curl -X POST https://app.sorbcloud.com/api/plugin/publish-tokens \
  -H "authorization: Bearer <your-project-key>" \
  -H "content-type: application/json" \
  -d '{"tokens":{"color-action-primary":"#f26722"},"name":"CI publish"}'

Dashboard session — the keys and org-administration routes have no key path; they manage the credentials and membership a key represents, so they're driven from a signed-in browser at app.sorbcloud.com, not curl. Every other route above accepts the same Bearer project key shown here instead of a session — that's how the Sorb MCP server and CI reach them.

Errors you'll actually see

Next

• Cloud & accounts — sign up, orgs, and keys.
• Tokenize a repo — the tokenize pipeline in depth.
• Token version to GitHub PR — the token-pr pipeline in depth.
• Troubleshooting — symptom → cause → fix.

Works with Figma. Not affiliated with, or endorsed by, Figma. Figma is a trademark of Figma, Inc.