A key can call an endpoint only when it holds that endpoint's scope.
Scopes are Muvia's own permission names — the same ones a role grants a
person, such as datasets_read. They are chosen when the key is issued, and an
administrator can change them later without changing the key's value.
| Endpoint | Scope |
|---|---|
GET /v1/company | settings_read |
GET /v1/projects, GET /v1/projects/{project_id} | settings_read |
GET /v1/projects/{project_id}/datasets, GET /v1/projects/{project_id}/datasets/{dataset_id} | datasets_read |
GET /v1/projects/{project_id}/datasets/{dataset_id}/rows | datasets_read |
GET /v1/projects/{project_id}/nodes, GET /v1/projects/{project_id}/nodes/{node_id} | nodes_read |
A key that reads everything v1 offers needs settings_read, datasets_read
and nodes_read. Grant only what the integration uses.
Calling an endpoint without its scope answers 403:
{
"error": {
"code": "forbidden",
"message": "The API key does not grant the required scope",
"status": 403
}
}
An administrator can grant a key only scopes they hold themselves, both when
issuing it and when changing it later. superadmin can never be granted to a
key.
A company's enabled modules cap every key, on every request. A scope that belongs to a module the company has switched off is taken out of the key for as long as the module stays off, and the endpoints that need it answer 403. The key itself stays valid and keeps its other scopes; switching the module back on gives the scope back.
The three scopes v1 uses belong to Muvia's core, which is always on, so today no module switch removes them. The rule holds for every scope the API adds later.
A key sees the company that issued it and nothing else. A project, dataset or node of another company answers 404, exactly like one that does not exist: the API never confirms that data outside your company exists.