Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Modellen Tools & Services
Oplossingen
Organisaties Ontwikkelaars Internet Service Providers Managed Service Providers AI-in-a-Box
Kenniscentrum
Ondersteuning Documentation Blog Downloads
Bedrijf
Over ons Onderzoek Vacatures Investeren Contact
Inloggen

Authentication

Every request to ScaiAtlas (except a handful of public auth endpoints) carries a bearer token:

text
1
Authorization: Bearer <token>

The server disambiguates by prefix: a token starting with sk_ is treated as an API key; anything else is validated as a ScaiKey JWT.

Authorization: Bearer is the only credential header the API reads, for API keys exactly as for tokens. There is no X-API-Key header; a request that sends one and nothing else is unauthenticated.

Credential types#

API keys#

Long-lived keys, ideal for services, pipelines, and CI. Create and manage them in the web UI (or via the admin API). The plaintext is shown once at creation.

python
1
2
3
4
from scaiatlas import ScaiAtlas
client = ScaiAtlas(api_key="sk_live_...", base_url="https://api.scaiatlas.io")
# or from SCAIATLAS_API_KEY / SCAIATLAS_BASE_URL:
client = ScaiAtlas.from_env()

API keys carry a permission mode:

  • explicit — the key's own permission list is authoritative.
  • inherited — the key inherits the full permissions of a linked user.
  • restricted — the intersection of a linked user's permissions and an explicit list.

inherited and restricted require a linked user.

Namespace-scoped keys#

A key can also be pinned to a set of namespaces. For such a key the permission list is a grant in its own right: within those namespaces, the key may do what its permissions say, with no namespace role behind it.

That is what makes a service principal workable. A key authenticates as itself, not as a person, so there is no identity to hang a member or admin role off.

Two boundaries are worth stating plainly:

  • Outside its namespaces a scoped key has nothing — not even the read access a public namespace normally grants to everyone. The restriction overrides visibility.
  • A key with no namespace restriction gains nothing from its permission list for namespace operations. It falls back to roles and visibility, so no key can grant itself the run of the deployment.

A worker key with view and download on two namespaces is therefore exactly that: it cannot upload, and it cannot see anything else.

jsonc
// POST /api/v1/admin/api-keys  (admin only)
{
  "name": "worker-01",
  "permission_mode": "explicit",
  "permissions": ["view", "download"],
  "namespace_ids": ["<ns-uuid>", "<ns-uuid>"]
}

Creating, updating and revoking keys requires admin access. The plaintext is returned once, at creation, and never again.

OAuth (browser, PKCE)#

For interactive apps. Opens a browser to authenticate against ScaiKey:

python
1
2
3
client = ScaiAtlas.with_oauth(client_id="my-app")
client.login()          # opens a browser, completes PKCE
client.namespaces.list()

Device flow (CLI / headless)#

For terminals and machines without a browser. Displays a URL and a code to enter elsewhere:

python
1
2
client = ScaiAtlas.with_device_flow()   # client_id defaults to "scaiatlas-cli"
client.login()          # prints verification URL + user code, polls until authorized

Under the hood this uses POST /api/v1/auth/cli/init to start a session, then polls GET /api/v1/auth/cli/status until a browser session authorizes it via POST /api/v1/auth/cli/authorize.

Who am I?#

python
1
me = client.get("/api/v1/auth/me")   # via REST: id, email, tenant_id, permissions, groups

The REST endpoint GET /api/v1/auth/me returns the current principal, its tenant, and its effective global permissions and groups.

Permission model#

Two layers combine on every request.

1. Global permissions#

Platform-wide grants carried on the identity (JWT claims + database rows). Tiered admin roles (scaiatlas:tenant_admin, scaiatlas:partner_admin) gate the admin API.

Do not rely on super-admin as a namespace bypass. It bypasses model-level checks, and my-permissions will report a super-admin as holding everything, but namespace-level checks do not honour it: the call can still be refused. Grant a namespace role or use a scoped key instead of depending on this. We are resolving the inconsistency in one direction or the other; until then, treat super-admin as an admin-API grant, not a skeleton key.

2. Namespace roles#

Within a namespace, a caller has a role, and each role grants a set of permissions:

Role Grants (cumulative)
viewer view, download
member viewer + create_model, update_own_model, delete_own_model, upload_version
admin member + update_any_model, delete_any_model, manage_members, update_namespace
owner admin + delete_namespace, transfer_ownership

Beyond explicit roles, visibility grants implicit read access: public namespaces grant view/download to anyone; tenant namespaces grant them to users in the same tenant.

Checking your own permissions#

bash
1
GET /api/v1/namespaces/{namespace}/my-permissions

Returns your effective role, the full permissions list, and where each permission came from. This is the same set the API enforces — the endpoint and the permission check read one resolver, so what it tells you you may do is what the next request will let you do.

For a namespace-scoped API key, role is null and the source names the key:

json
1
2
3
4
5
{
  "role": null,
  "permissions": ["download", "upload_version", "view"],
  "inherited_from": [{"type": "api_key", "api_key_id": "…"}]
}

role: null is correct there, not an error — a service principal has no namespace role. Drive your logic off permissions, not role.

For a namespace you have no access to, the answer is 200 with an empty list, not 403:

json
1
{"role": null, "permissions": [], "inherited_from": []}

inherited_from entries are {"type": "direct"|"group"|"api_key", …}.

Managing members#

python
1
2
3
client.namespaces.add_member("poolnoodle", user_id="<uuid>", role="member")
client.namespaces.list_members("poolnoodle")
client.namespaces.remove_member("poolnoodle", user_id="<uuid>")

Membership can be granted to a user or a group (REST accepts user_id or group_id). The last owner cannot be demoted or removed.

Environment variables#

Variable Purpose
SCAIATLAS_API_KEY API key for from_env().
SCAIATLAS_BASE_URL Registry base URL (default https://api.scaiatlas.io).
SCAIATLAS_TIMEOUT Request timeout in seconds.
SCAIATLAS_VERIFY_SSL true/false.

Minting worker keys#

A key that carries manage_worker_keys can issue download-only keys inside its own scope, so a fleet that adds and removes machines does not need a request to the registry team each time.

text
1
2
3
POST   /api/v1/worker-keys          mint one; the secret is in the response
GET    /api/v1/worker-keys          list the keys this key minted
DELETE /api/v1/worker-keys/{id}     revoke one of them

The request carries a name, an optional description and an optional expires_in_days. It cannot carry permissions or namespaces: those are copied from the minting key, so there is no field through which a caller could widen what it issues. A minted key gets view and download, in exactly the minting key's namespaces.

The secret is returned once and only its hash is stored. The key works on its first call — the registry commits it before answering.

Four rules keep delegation from becoming escalation:

  • A minted key can only view and download, and the minter must hold both.
  • A minted key reaches exactly the minter's namespaces, never more.
  • A minted key cannot mint. There is no second generation.
  • A key with no namespace restriction cannot mint at all, since scope is inherited and it would hand out unrestricted keys.

A minter lists and revokes only the keys it minted; another key's worker is reported as not found. Rotation needs nothing special: mint the new key, deploy it, then revoke the old one — several keys can be active at once.

Updated 2026-10-17 15:32:40 View source (.md) rev 3