Auth and tenancy
Browser sessions, SDK API keys, workspace isolation, scopes, and permission checks.
InstantML deliberately uses different credentials for humans and training jobs, and both resolve to exactly one workspace before any product data is read or written.
| Credential | Transport | Main use |
|---|---|---|
| Browser session | instantml_session HttpOnly cookie | Dashboard after hosted sign-in. |
| SDK API key | Authorization: Bearer instantml_... | SDK, uploader, imports, exports, and automation. |
The identity provider's session token never becomes the SDK credential, and the SDK API key never depends on the identity provider.
Browser sign-in flow
| Step | Caller | Action |
|---|---|---|
| 1 | Browser | GET /api/auth/config to learn the available auth providers. |
| 2 | Browser | Sign in or sign up with the configured identity provider (Clerk on the hosted service). |
| 3 | Browser | Submit the provider token to POST /api/auth/clerk. |
| 4 | InstantML API | Verify the token signature, issuer, and verified email. |
| 5 | InstantML API | Upsert user, workspace, membership, and session records in the control plane. |
| 6 | InstantML API | Provision or load the workspace's tenant route. |
| 7 | InstantML API | Return the auth payload and set the browser session cookie. |
Cookie-authenticated mutating requests validate Origin against the allowed frontend origins. Bearer-token SDK requests are not origin-gated because they are not browser-cookie requests.
The CLI signs in without a browser cookie: instantml login uses the device-code flow (/api/auth/device-code/*) to mint an API key after you confirm the code in the dashboard. See CLI login.
API-key flow
| Stage | What happens |
|---|---|
| Bearer key | The request presents Authorization: Bearer instantml_.... |
| Key authentication | The API authenticates the key hash; plaintext keys are never stored. |
| Tenant resolution | The API resolves the workspace (org_id) and any project scope attached to the key. |
| Route lookup | The API loads the tenant route for that workspace. |
| Scope checks | The route handler enforces API-key scopes and project boundaries. |
| Product access | The request reads or mutates tenant data. |
Project-scoped API keys can only read or mutate their project. Workspace-scoped keys can access every project allowed by their scopes.
API-key scopes
| Scope | Grants |
|---|---|
sdk:ingest | Create projects and runs, log metrics, logs, attributes, and objects. |
artifacts:write | Upload artifacts and create artifact versions. |
artifacts:manage | Manage artifact collections, aliases, and retention. |
imports:write | Create import jobs. |
export:read | Read data exports. |
usage:read | Read usage summaries (unrestricted workspace keys only). |
api_keys:write | Administer API keys. |
runs:control | Record cooperative stop signals for runs. |
Permission matrix
| Route class | API key | Owner/admin session | Member session | Viewer session |
|---|---|---|---|---|
| Dashboard reads | Scope and workspace/project checks | Allowed | Allowed | Allowed |
| Run/project mutations | sdk:ingest | Allowed | Allowed | Denied |
| Artifact mutations | artifacts:write | Allowed | Allowed | Denied |
| Imports | imports:write | Allowed | Denied | Denied |
| Reports | Same-workspace key for writes; same-workspace key or share token for reads | Allowed | Read/write allowed | Reads allowed; writes denied |
| Usage reads | Unrestricted workspace key with usage:read | Allowed | Denied | Denied |
| API-key admin | api_keys:write workspace key | Allowed | Denied | Denied |
| Seat and invitation admin | Not a public SDK flow | Allowed | Denied | Denied |
Shared demo sessions
The shared demo workspace is read-only. Demo credentials are treated as export:read at authorization time, so demo sessions can browse and export sample data but cannot create runs, mutate artifacts, import data, administer API keys, or change seats.
Tenant boundaries
Every tenant-owned product row carries the workspace's org_id, and run and project helpers reject rows from a different workspace. Project-scoped keys add a second boundary around a single project.
Sign-out and revocation
POST /api/auth/logout revokes the current browser session and clears the cookie. Revoked or expired sessions are rejected on the next request.
Removing a user from a workspace invalidates their effective access immediately, because building a session payload requires an active membership.