Authentication
Two headers: the API key that identifies you, and the workspace whose data you're reading.
Every call carries two headers. One authenticates you, the other says which workspace you're reading from.
X-API-Key: <your api key>
workspace_id: <workspace id>workspace_id is a header, not a query parameter, and its name is lowercase with an underscore. Put it in the query string and the call fails with 422, naming workspace_id as a missing header — headers are validated before the query string is looked at, so the stray parameter is never even read as a filter.
The API key
Simetrik issues it for your account. It's a server-side credential: it isn't scoped to a user, it doesn't expire on its own, and anything holding it can read the data of every workspace it's allowed to reach. Keep it in your secret store and out of browsers, repositories and logs.
Rotate it through Simetrik if you suspect it leaked.
The workspace
workspace_id must be the numeric id of the workspace that owns the resource you're asking for. Three checks run on every call, in this order:
The key is valid
A key that doesn't match is rejected with 401.
The workspace exists
An unknown workspace is 404.
The resource belongs to that workspace
A resource from a different workspace is 403, even if your key is perfectly valid. Ownership is checked before anything is read, so this answer is consistent — you'll never get data from a workspace you didn't name.
What each failure looks like
| Status | Body | Cause |
|---|---|---|
401 | Could not validate credentials | The key doesn't match. A call with no X-API-Key header at all is rejected as unauthenticated too. |
422 | Validation error naming workspace_id | The header is missing — including when it was sent as a query parameter instead. |
400 | workspace_id must be a valid integer | The header is there but isn't a number. |
404 | Workspace not found | No workspace with that id. |
403 | Resource does not belong to the specified workspace | The resource belongs to another workspace. |
CORS
The API is built to be called from a backend. Browser calls are only possible from origins your account has explicitly allowed — and putting a long-lived API key in a browser is a bad idea regardless, so treat this as a server-to-server integration.