# Auth and tenancy

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. |

> **Note:** Local single-binary deployments run in dev auth mode instead and sign in through `POST /api/auth/dev/google`. That route is disabled on the hosted service.

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](/docs/sdk/cli-login.md).

## 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.

## Next steps

- [API authentication](/docs/api/authentication.md)
- [SDK installation and auth](/docs/sdk/installation-auth.md)
- [CLI login](/docs/sdk/cli-login.md)
- [Settings and API keys](/docs/dashboard/settings-api-keys.md)
- [Service planes](/docs/architecture/service-planes.md)

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md)
- [Logging](/docs/sdk/logging.md)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md) (current page)
- [Schema Reference](/docs/architecture/schema-reference.md)

### API Reference

- [API Reference](/docs/api-reference.md)