Org-scoped service key returns 403 on workspace-scoped resources

Last updated: September 23, 2026

Symptom

A service account or other organization-scoped API/service key has a role with the permissions needed for a workspace-scoped resource (for example, annotation queues). This might be the built-in Admin role, or a custom role with the exact permission assigned. Calls to that workspace-scoped endpoint still return 403 Forbidden.

Calls made with the same key to organization-scoped endpoints (for example, listing organization users) succeed. Only workspace-scoped endpoints fail. This looks like an RBAC or permissions problem, but the role configuration is not the issue.

Cause

The key is organization-scoped, and the request to the workspace-scoped resource is missing the X-Tenant-Id header (the workspace ID). An organization-scoped key isn't tied to a single workspace, so the API has no way to know which workspace's data to authorize or return without that header, and it rejects the request with 403 Forbidden regardless of what the assigned role permits.

If X-Tenant-Id is omitted, requests fall back to the workspace the key was originally created in. A key created as organization-scoped has no such workspace to fall back to, so instead of defaulting anywhere, the request fails with 403.

Resolution

Include the X-Tenant-Id header, set to the target workspace's ID, on every request to a workspace-scoped resource made with an organization-scoped service key.

  • X-Organization-Id should be present on all requests made with the key.

  • X-Tenant-Id should be present specifically on requests scoped to a particular workspace, with its value set to that workspace's ID.

This applies to any workspace-scoped resource, not just annotation queues: any endpoint tied to a specific workspace requires the header when called with an organization-scoped key. Adding it resolves the 403 without any change to the role or its permissions.

References