Skip to main content

​
Find the workspace ID

Select your workspace in Agent Builder, then open API & Developers → REST API. Copy the displayed Workspace ID. This positive integer is the local workspace/group identifier used by X-VOAI-ORGANIZATION-ID; it is not a tenant UUID, agent ID, or agent UUID.

​
API-key requests

Send your key and workspace ID together. The same key can be used with another workspace ID only when its owner is currently a member of that workspace.
A missing or invalid workspace ID returns 400. A workspace the owner cannot access returns 403. Resource IDs must also belong to the requested workspace. A valid empty list means no matching resources were returned; it does not by itself mean authentication failed.

​
Bearer and MCP requests

REST bearer requests and MCP connections use the account’s selected workspace. MCP’s switch_workspace changes that selection across clients. It does not change the workspace header your REST integration sends with an API key. See MCP workspace selection.

​
Roles

The endpoint’s authorization requirements take precedence over this summary. For example, a read-like export can require Editor access, and a write can have additional resource or provider conditions. The separate Labs super_user role is required for some bearer-only operations and is not granted by workspace ownership. Keys follow current permissions. Removing membership or changing a role changes what subsequent requests can do. See roles and permissions and authentication.