--- title: Workspaces and access | Luma Agents description: Create workspaces to hold your assets and, if you serve several customers, keep each one's workspaces apart. --- A workspace is a storage location for assets, like a project folder. Every session lives in one, and everything a session makes or receives stays there, where other sessions in the workspace can find it. On the wire a workspace is a scope (`scope_id`, `/v1/scopes`). How you divide work into workspaces is up to you: one per brand, per campaign, per project or per end user. ## Create a workspace - [cURL](#tab-panel-0-0) - [Python](#tab-panel-0-1) - [TypeScript](#tab-panel-0-2) ```bash WORKSPACE_ID=$(curl -s -X POST https://agents.lumalabs.ai/v1/scopes \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "key": "spring-campaign", "display_name": "Example Bakery, spring campaign" }' \ | jq -r .scope_id) ``` ```python import json import os import urllib.request BASE = "https://agents.lumalabs.ai/v1" def post(path, body, token, headers=None): request = urllib.request.Request( BASE + path, method="POST", data=json.dumps(body).encode(), headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", **(headers or {})}, ) with urllib.request.urlopen(request) as response: return json.load(response) workspace_id = post( "/scopes", { "key": "spring-campaign", "display_name": "Example Bakery, spring campaign", }, session_token, )["scope_id"] ``` ```typescript const BASE = "https://agents.lumalabs.ai/v1"; async function post( path: string, body: unknown, token: string, headers: Record = {}, ) { const response = await fetch(BASE + path, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...headers, }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); return response.json(); } const { scope_id: workspaceId } = await post( "/scopes", { key: "spring-campaign", display_name: "Example Bakery, spring campaign", }, sessionToken, ); ``` `key` is your name for the workspace. Posting the same `key` again returns the same workspace, so you can call this on every request without creating duplicates. `GET /v1/scopes` lists the workspaces a token can see, and `GET /v1/scopes/$WORKSPACE_ID` reads one. Fonts and [skills](/agents/skills/index.md) can also belong to one workspace: pass its `scope_id` when you create them. ## Keep customers apart If your product serves several customers, you can keep each customer’s workspaces apart with a `tenant_id`. It’s optional: without one, all your workspaces sit together under your API key. Set `tenant_id` to your id for the customer, such as an account or organization id, on every token you mint for that customer’s users. Each customer then has their own workspaces, one or many: ON YOUR SERVER API key LUMA\_AGENTS\_API\_KEY never leaves your server HANDED TO YOUR USERS Session token tenant\_id: acme user\_id: user-8812 Session token no tenant\_id keep it on your server mints Your Luma account every workspace you create Customer acme workspaces created with tenant\_id acme Workspace key: spring-campaign assets shared by acme’s users sessions seen by their own user Workspace key: brand-workspace assets shared by acme’s users sessions seen by their own user Customer globex its own workspaces; acme’s tokens get 404 even one with the same key Workspaces with no tenant\_id created by tokens without a tenant\_id, reachable by every such token A token reaches only the workspaces of its `tenant_id`, and a token without one reaches only workspaces created without one. Inside a workspace, assets are shared by all of that customer’s users; each session is visible only to the `user_id` that opened it. - [cURL](#tab-panel-1-0) - [Python](#tab-panel-1-1) - [TypeScript](#tab-panel-1-2) ```bash curl -s -X POST https://agents.lumalabs.ai/v1/auth/token \ -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "user_id": "user-8812", "tenant_id": "customer-4417" }' ``` ```python print(post( "/auth/token", {"user_id": "user-8812", "tenant_id": "customer-4417"}, os.environ["LUMA_AGENTS_API_KEY"], )) ``` ```typescript console.log( await post( "/auth/token", { user_id: "user-8812", tenant_id: "customer-4417" }, process.env.LUMA_AGENTS_API_KEY!, ), ); ``` A token with a `tenant_id` sees only that customer’s work: - `GET /v1/scopes` lists only that customer’s workspaces. - Another customer’s workspace answers `404 SCOPE.NOT_FOUND`, whether you read it, open a session in it or upload to it. - The same `key` under two customers makes two separate workspaces, so both can use `"key": "brand-workspace"`. - A workspace takes its customer from the token that created it, and keeps it for good. A token minted without a `tenant_id` can list and open every workspace created without one, whoever created it. Keep such tokens on your server. Any token you hand to a browser or a mobile app must carry the customer’s `tenant_id`. Within one customer, a workspace is shared. The agent’s asset search covers every asset in it, whichever user made or uploaded it. `user_id` records who did the work but doesn’t hide it. If two users of the same customer must not see each other’s assets, give each one their own workspace. ## Token permissions A token’s permissions are listed in its `scopes` field. They gate a few routes, not the whole API. | Permission | Required by | | ------------- | --------------------------------------------------------------------------------------------------- | | `generate` | Creating a session, sending a message, starting a run, and every `/v1/skills` and `/v1/fonts` call. | | `tools:write` | Answering a tool call. `tools:*` also grants it. | By default a token gets `generate`, `tools:*`, `tools:read` and `tools:write`. Pass a narrower `scopes` array when you mint it to grant less. A missing permission answers `403 AUTH.SCOPE_FORBIDDEN`. A token with fewer permissions is not read-only. It can still close sessions, cancel runs, upload files and create workspaces. Keep its `ttl` short and give it only to the user it was minted for. ## Details - A token’s `ttl` runs from 60 to 86,400 seconds, 3,600 by default. A token keeps working until it expires, even after you revoke the API key that minted it. During an emergency rotation, also close the affected sessions. - `user_id` is opaque to Luma. Send a stable id, never an email address. Luma forwards it to model providers as their per-user field, so a trust and safety signal points at one end user rather than your whole account. - `DELETE /v1/scopes/$WORKSPACE_ID` deletes it, its assets and its fonts, and frees its `key`. Call it from your backend: with a token minted for that customer, or with the API key for workspaces created without a `tenant_id`. A token without a `tenant_id` can’t delete anything. A workspace with an active session answers `409 SCOPE.HAS_ACTIVE_SESSIONS`; close its sessions first. - `GET /v1/sessions?scope_id=$WORKSPACE_ID` lists one workspace’s sessions. - `GET /v1/usage?group_by=tenant_id` reports spend per customer. See [Budgets and usage](/agents/budgets/index.md). ## Next - [Instructions and references](/agents/instructions/index.md): give the agent standing instructions and references. - [Sessions](/agents/sessions/index.md): work inside a workspace.