Skip to content

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.

Terminal window
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)

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.

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.

Terminal window
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" }'

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.

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.

A token’s permissions are listed in its scopes field. They gate a few routes, not the whole API.

PermissionRequired by
generateCreating a session, sending a message, starting a run, and every /v1/skills and /v1/fonts call.
tools:writeAnswering 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’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.