Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Workspaces

The Scripe API is workspace-scoped end-to-end: every read returns data only the active workspace owns. /v1/workspaces/me resolves the active workspace plus the principal that’s calling; /v1/workspaces lists every workspace the caller can reach. API keys authorise exactly one workspace — to act on a different workspace, mint a key there. OAuth tokens can reach every workspace the consenting user belongs to: the workspace pinned at consent is the default, and a per-request Scripe-Workspace-Id header targets any other (see Multi-workspace access).

​
GET /v1/workspaces/me

Returns the authenticated workspace’s metadata, the principal making the request, and the feature flags currently enabled for the workspace’s plan. 
curl -i https://api.scripe.io/v1/workspaces/me \
  -H "Authorization: Bearer scripe_sk_live_…" \
  -H "Scripe-Api-Version: 2026-08-01"

​
Response

HTTP/1.1 200 OK
Content-Type: application/json
Scripe-Api-Version: 2026-08-01
X-Request-Id: req_01J9Z…

{
  "workspace": {
    "id": "org_2pYJfL3VpQK4G2J7nE9b6Vw",
    "name": "Acme Corp",
    "plan": "ADVANCED",
    "features": {
      "apiAccess": true,
      "amplifiers": false,
      "engagementAutomation": false
    }
  },
  "principal": {
    "type": "api_key",
    "id": "key_01J9ZAB12CD34E56F7G8H9",
    "scopes": ["notes:read", "posts:read"]
  }
}

​
Field reference

PathTypeNotes
workspace.idstring (org_*)Clerk organisation id. Stable for the lifetime of the workspace.
workspace.namestring | nullHuman-readable label set in the dashboard. Cached for 60 s.
workspace.planstringOne of FREE, SOLO, ADVANCED, BUSINESS, ENTERPRISE, TRIAL.
workspace.featuresobjectBoolean feature flags currently enabled by the plan.
workspace.features.apiAccessbooleanIf false, the API would have already 401’d. Always true here.
principal.type"api_key"Reserved for future OAuth-token ("oauth") and impersonation flows.
principal.idstring (key_*)The canonical id of the API key in use.
principal.scopesstring[]The scopes the key carries (subset of the global catalogue).
The features object grows over time. Treat unknown keys as false when introspecting; a true for a flag we haven’t shipped yet means your client predates the dashboard’s option.

​
Caching

The response is not cacheable — it depends on the request’s principal and reflects live plan state. Don’t memoise it for longer than it takes to render the next page. If you need workspace metadata frequently (e.g. you’re showing the plan in your UI), cache the response in your own client for a minute and invalidate on plan-change webhooks.

​
Why not just decode the API key?

Two reasons:
  1. Plan changes propagate. The plan in the response reflects the workspace’s current Stripe state, not what was true when you minted the key. A workspace that downgrades will see apiAccess: false here before any other endpoint starts 403’ing.
  2. Forward-compat. When OAuth tokens land, the same endpoint will return principal.type: "oauth" and surface the user delegating access. Clients that already use this endpoint Just Work.

​
Errors

StatusCode
401unauthenticated, invalid_token, key_revoked, key_expired
403plan_not_eligible
429rate_limited
503service_unavailable
See errors/ for full descriptions.

​
GET /v1/workspaces

Lists every workspace the caller can reach. For an OAuth token that is every Clerk organisation the consenting user is currently a member of (live membership); for an API key it is the single workspace the key is bound to. 
curl -i https://api.scripe.io/v1/workspaces \
  -H "Authorization: Bearer scripe_oat_…" \
  -H "Scripe-Api-Version: 2026-08-01"

​
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "workspaces": [
    { "id": "org_2pYJfL3VpQK4G2J7nE9b6Vw", "name": "Acme Corp", "isDefault": true },
    { "id": "org_2qKd…",                    "name": "Client A",  "isDefault": false },
    { "id": "org_2rLe…",                    "name": "Client B",  "isDefault": false }
  ]
}

​
Field reference

PathTypeNotes
workspaces[].idstring (org_*)Clerk organisation id. Use as the Scripe-Workspace-Id header value.
workspaces[].namestringHuman-readable label. Cached for 60 s.
workspaces[].isDefaultbooleanThe workspace used when no Scripe-Workspace-Id header is sent.

​
Multi-workspace access

A single OAuth token can operate against any workspace the consenting user belongs to. Select the target per-request with the Scripe-Workspace-Id header (value = the org_* id from GET /v1/workspaces): 
# Read Client A's posts with the same token used for the default workspace
curl -i "https://api.scripe.io/v1/posts?projectId=proj_…" \
  -H "Authorization: Bearer scripe_oat_…" \
  -H "Scripe-Workspace-Id: org_2qKd…" \
  -H "Scripe-Api-Version: 2026-08-01"
  • Default. Omit the header → the request runs against the consent-pinned (default) workspace. /v1/workspaces/me reflects the active workspace, so it changes with the header.
  • Live membership. Access is validated against the user’s current Clerk membership on every request (60 s cache). A header naming a workspace the user is not a member of returns workspace_unavailable.
  • Plan. Gating inherits the default workspace’s plan, so client workspaces on cheaper plans still work under an API-enabled token.
  • API keys are single-workspace. A Scripe-Workspace-Id header that disagrees with the key’s workspace is rejected with workspace_unavailable.

​
What’s NOT here (yet)

  • Switching workspaces with an API key. Not supported — API keys are bound to one workspace. Use an OAuth token (with Scripe-Workspace-Id) or mint a key in the target workspace.
  • Updating workspace metadata (renaming the workspace, changing the plan). Use the Scripe dashboard. Phase 3 may add a write PATCH /v1/workspaces/me for the subset of fields that make sense programmatically.