Workspaces and access
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
Section titled “Create a workspace”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)import jsonimport osimport 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"]const BASE = "https://agents.lumalabs.ai/v1";
async function post( path: string, body: unknown, token: string, headers: Record<string, string> = {},) { 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 can also belong to one workspace: pass its scope_id when you create them.
Keep customers apart
Section titled “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:
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 -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" }'print(post( "/auth/token", {"user_id": "user-8812", "tenant_id": "customer-4417"}, os.environ["LUMA_AGENTS_API_KEY"],))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/scopeslists 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
keyunder 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.
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
Section titled “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.
Details
Section titled “Details”- A token’s
ttlruns 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_idis 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_IDdeletes it, its assets and its fonts, and frees itskey. Call it from your backend: with a token minted for that customer, or with the API key for workspaces created without atenant_id. A token without atenant_idcan’t delete anything. A workspace with an active session answers409 SCOPE.HAS_ACTIVE_SESSIONS; close its sessions first.GET /v1/sessions?scope_id=$WORKSPACE_IDlists one workspace’s sessions.GET /v1/usage?group_by=tenant_idreports spend per customer. See Budgets and usage.
- Instructions and references: give the agent standing instructions and references.
- Sessions: work inside a workspace.