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

Path	Type	Notes
`workspace.id`	string (`org_*`)	Clerk organisation id. Stable for the lifetime of the workspace.
`workspace.name`	string \| null	Human-readable label set in the dashboard. Cached for 60 s.
`workspace.plan`	string	One of `FREE`, `SOLO`, `ADVANCED`, `BUSINESS`, `ENTERPRISE`, `TRIAL`.
`workspace.features`	object	Boolean feature flags currently enabled by the plan.
`workspace.features.apiAccess`	boolean	If `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.id`	string (`key_*`)	The canonical id of the API key in use.
`principal.scopes`	string[]	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:

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.
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

Status	Code
401	`unauthenticated`, `invalid_token`, `key_revoked`, `key_expired`
403	`plan_not_eligible`
429	`rate_limited`
503	`service_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

Path	Type	Notes
`workspaces[].id`	string (`org_*`)	Clerk organisation id. Use as the `Scripe-Workspace-Id` header value.
`workspaces[].name`	string	Human-readable label. Cached for 60 s.
`workspaces[].isDefault`	boolean	The 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.

Getting started

Resources

Errors

Workspaces

Workspaces

`GET /v1/workspaces/me`

Response

Field reference

Caching

Why not just decode the API key?

Errors

`GET /v1/workspaces`

Response

Field reference

Multi-workspace access

What’s NOT here (yet)

​Workspaces

​GET /v1/workspaces/me

​Response

​Field reference

​Caching

​Why not just decode the API key?

​Errors

​GET /v1/workspaces

​Response

​Field reference

​Multi-workspace access

​What’s NOT here (yet)

Workspaces

`GET /v1/workspaces/me`

Response

Field reference

Caching

Why not just decode the API key?

Errors

`GET /v1/workspaces`

Response

Field reference

Multi-workspace access

What’s NOT here (yet)