Workspace scope

A request serves the workspace of its credential. Some routes can also serve another workspace, or several workspaces in one call. Send the optional x-corma-workspace-ids header to select the workspaces.

Identifying compatible routes

In the API reference, a compatible route has one of these badges:

Badge	The route can serve
Workspace scope	One workspace: the workspace of the credential, or one other workspace.
Multi-workspace	One workspace or more.

A compatible route also documents the x-corma-workspace-ids header in its operation details.

A route without these badges serves only the workspace of the credential. On such a route, do not send the header, or send only the id of the workspace of the credential.

Request header

Header	Required	Description
`x-corma-workspace-ids`	No	A comma-separated list of workspace ids, for example `12,34`. Spaces around the commas are permitted. A repeated id counts one time. The maximum is 100 workspaces.

The API reads the header in three ways:

Header	Scope	The request serves
Absent	Implicit	The workspace of the credential. This is the behavior of a request without the header.
One id	Explicit	The workspace that the header names.
More than one id	Multiple	All the workspaces that the header names. A Multi-workspace route only.

Rules for each credential

API key. An API key belongs to one workspace. The header can name only that workspace. Any other id gets 403 Forbidden.

Bearer token. A bearer token belongs to one person and one workspace. The person must be an admin member of the workspace of the token, also when the header does not name it. The header can name each workspace where that person is an admin member. If the person is not an admin member of one of the named workspaces, the request gets 403 Forbidden. The response does not tell which workspace failed.

The API checks the credential before the route. An API key that names another workspace gets 403 Forbidden on each route, also on a route without a badge.

Errors

Each error carries a stable data.code. Use the code to handle the error. The message can change.

Status	`data.code`	Cause
`400 Bad Request`	`malformed_header`	The value is empty, or a part of it is not a positive integer.
`400 Bad Request`	`too_many_workspaces`	The header names more than 100 workspaces.
`400 Bad Request`	`route_not_workspace_scoped`	The route has no workspace scope badge, and the header names a workspace that is not the workspace of the credential.
`400 Bad Request`	`route_single_workspace`	The route has the Workspace scope badge, and the header names more than one workspace.
`403 Forbidden`	`api_key_foreign_workspace`	An API key names a workspace that is not its workspace.
`403 Forbidden`	`not_an_admin_member`	A bearer token names a workspace where its person is not an admin member.

Example of an error body:

{
  "code": "FORBIDDEN",
  "status": 403,
  "message": "An API key can only scope its own workspace",
  "data": { "code": "api_key_foreign_workspace" }
}

Examples

Implicit scope. The request serves the workspace of the API key:

GET /v1/example HTTP/1.1
x-corma-api-key: API_KEY_ID:API_KEY_SECRET

Multiple scope. The request serves workspaces 12 and 34. The person of the token must be an admin member of the two workspaces:

GET /v1/example HTTP/1.1
Authorization: Bearer TOKEN
x-corma-workspace-ids: 12,34

Idempotency

Mutation payloads