Scope Requests to a Teamspace

Learn how to create an API key that can reach other teamspaces, and how to scope requests to them

Teamspaces isolate resources and data within your organization. Every API key belongs to the teamspace it was created in — its home teamspace — and requests run there by default.

To run a request in a different teamspace, send that teamspace’s ID in the Datagrid-Teamspace header. Whether the header is honored depends on the key’s Teamspaces Access, which you choose when you create the key.

​

Create a key that can switch teamspaces

In the Datagrid web app, open Settings → API Keys from the teamspace you want as the key’s home, click Create API Key, and under Teamspaces Access choose:

• All Teamspaces — the key can reach every current and future teamspace in your account.
• Selected Teamspaces — the key can reach only the teamspaces you pick. The home teamspace is always included, and you can add or remove teamspaces later from the key’s Edit Teamspaces menu.

Only teamspace admins and owners can create API keys. The Teamspaces Access type can’t be changed after the key is created; to switch between All and Selected, create a new key.

The key still acts as the user who created it. A request in another teamspace succeeds only if that user also has access to the target teamspace and its resources.

​

How the header is applied

Teamspaces Access (scopeLevel)	Datagrid-Teamspace behavior
All Teamspaces ("account")	Selects any teamspace in the same account as the home teamspace. Any other teamspace returns 404.
Selected Teamspaces ("org"), with other teamspaces selected	Selects any teamspace on the key’s list. Any other teamspace returns 404.
Selected Teamspaces ("org"), home teamspace only	Ignored. The request always runs in the home teamspace.

Without the header, every request runs in the home teamspace. Keys created before the Teamspaces Access setting existed behave like Selected Teamspaces with only the home teamspace.

To check which teamspace a request resolved to, call GET /v1/identity with the same key and header and read current_teamspace_id. This confirms where the request runs, not that the key’s creator can access resources there. Each teamspace’s ID is shown in its own Settings → API Keys page.

​

Option 1: Initialize the client with a teamspace

Initialize the Datagrid client with a teamspace ID — all subsequent requests will use it automatically. The SDKs also read the ID from the DATAGRID_TEAMSPACE_ID environment variable.

Python

from datagrid_ai import Datagrid

datagrid = Datagrid(
    teamspace="teamspace_id",
)

response = datagrid.converse(
    prompt="Hello world!",
)

print(response.content[0].text)

​

Option 2: Scope individual requests

Pass the Datagrid-Teamspace header per request — useful when one client addresses several teamspaces.

Python

from datagrid_ai import Datagrid

datagrid = Datagrid()

response = datagrid.converse(
    prompt="Hello world!",
    extra_headers={
        "Datagrid-Teamspace": "teamspace_id",
    },
)

print(response.content[0].text)