Organizations, Users, and Workspaces
Purpose and Scope
This page orients administrators and SDK integrators who need to enumerate Claude Enterprise organization data: linked organizations, users, roles, groups, group members, workspaces, and effective organization settings. In first-party Claude documentation this is the directory and administration side of the platform, used for eDiscovery preparation, reporting dashboards, access reconciliation, workspace governance, and compliance review. The TypeScript SDK is the client-side implementation context for those calls, so this page focuses on the operational shape of these resources and the runtime constraints that matter when you build an admin or compliance integration in JavaScript or TypeScript.
The important distinction is between directory-style compliance data and workspace administration. The Compliance API documentation describes organization hierarchy traversal, role and group enumeration, and effective settings retrieval. Workspaces, by contrast, organize API usage, API keys, members, and cost controls within an organization. Both concepts are organization-scoped, but they solve different problems: compliance endpoints answer “what exists and what policy is in force,” while workspace administration answers “where usage and access are allocated.” Treating these as separate layers helps keep audit pipelines independent from day-to-day workspace lifecycle automation.
The repository evidence for this page is about how the SDK executes these calls across JavaScript runtimes. The generated platform detector adds Stainless runtime metadata such as language, SDK package version, operating system, architecture, runtime, and runtime version to requests. That matters for administrative tools because these integrations are often scheduled jobs, server-side dashboards, or edge-deployed reporting services, and the SDK deliberately distinguishes Node.js, Deno, edge, browser, and unknown environments. Sources: src/internal/detect-platform.ts
Relevant Source Files
- src/internal/detect-platform.ts — Defines runtime and platform detection used by the SDK to describe JavaScript execution environments, including Node.js, Deno, Edge Runtime, browser variants, and unknown runtimes.
- CLAUDE.md — Captures repository rules for keeping most SDK code runtime-agnostic and isolating Node-only imports, which is relevant when building admin integrations that must bundle correctly outside Node.js.
Core Administrative Concepts
An organization is the top-level administrative boundary for Claude platform usage. In the Compliance API documentation, a Compliance Access Key is bound to a parent organization and can return data for linked organizations underneath that hierarchy. A user is an identity inside an organization, a role defines permissions, and a group represents role-based access control or SCIM-provisioned membership. The effective settings endpoint complements the directory resources by returning the enforced data-privacy, security, and capability settings actually in force for one organization, not merely the values visible or configured in an administrative UI.
A workspace is a usage and access partition inside an organization. The workspace documentation describes a Default Workspace, additional workspaces with identifiers prefixed by wrkspc_, API keys scoped to a single workspace, member assignment, role assignment, and resource limits. This makes workspaces a practical boundary for projects, teams, environments, and cost controls. The Claude Code workspace has special behavior: it is created automatically when members sign in through Claude Code with Console billing, it mints per-user keys, and archiving it disables that sign-in path for the organization.
When designing an integration, use organization and compliance resources for inventory, audit, and policy questions, and use workspace resources for operational governance. For example, a compliance dashboard might first list organizations, then enumerate users and groups for each organization, and finally retrieve effective settings to show what capabilities and privacy controls are enforced. A workspace cost-control tool would instead focus on workspace membership, API keys, limits, and role assignment. Both workflows are administrative, but their authentication requirements and failure modes should be handled independently.
Authentication and Access Model
The Compliance API documentation calls out a specific access pattern: the relevant endpoints require Compliance Access Keys, not Admin API keys. The organization, role, group, and settings endpoints require read:compliance_org_data, while user and group-member endpoints require read:compliance_user_data. A call made with an Admin API key is documented as returning 403 Forbidden for these compliance endpoints. In practice, this means integrations should validate key provenance before running long enumerations, because a syntactically valid Anthropic-looking key may still be the wrong key type for compliance data.
Pagination is part of the organization-listing contract. The official documentation describes a data array sorted by created_at ascending and pagination fields such as has_more and next_page. When has_more is true, callers pass the returned token back unchanged as the page query parameter. Administrative jobs should preserve that token exactly, avoid assuming offset-style pagination, and store enough progress state to resume safely if a scheduled run is interrupted. This is especially important for parent organizations with many linked organizations and for downstream jobs that fan out into users, groups, and settings.
Because these calls can run from different JavaScript environments, credential handling should stay server-side unless a use case explicitly allows browser access. The platform detector includes browser identification, but the repository’s runtime guidance emphasizes avoiding accidental exposure of secret credentials in browser builds. Administrative and compliance keys are high-sensitivity credentials, so the safest architecture is a backend job, serverless function, or controlled edge service that keeps keys outside client-side code. The SDK’s environment detection helps label requests, but it is not a substitute for key hygiene and deployment isolation. Sources: src/internal/detect-platform.ts
System-to-Code Mapping
The SDK’s platform detection starts by determining whether the process is Deno, Edge Runtime, Node.js, browser, or unknown. For Deno it reads Deno.build and Deno.version; for Node.js it reads guarded globalThis.process fields; for Edge Runtime it emits an edge runtime label; and for browsers it derives browser name and version from the user agent. The returned platform properties include X-Stainless-Lang, X-Stainless-Package-Version, X-Stainless-OS, X-Stainless-Arch, X-Stainless-Runtime, and X-Stainless-Runtime-Version. Administrative integrations do not usually call this module directly, but every request benefits from consistent client telemetry. Sources: src/internal/detect-platform.ts
The repository’s contributor guidance reinforces why admin-oriented code should be runtime-aware. Node-only code must live in a module named node.ts or a node/ directory, and SDK-internal code should not import Node-only modules statically or dynamically unless it is unavoidable and properly shimmed through the package browser field. The guidance also warns that bundlers follow statically resolvable imports, including lazy relative imports, which can break browser builds if Node builtins appear in reachable chunks. For admin tooling, that means file-system credential loading, local certificate handling, or enterprise proxy setup should remain in clearly Node-specific application code, not in shared browser bundles. Sources: CLAUDE.md
This mapping gives a practical design rule: keep the resource workflow portable, and isolate deployment-specific concerns. The organization enumeration loop, pagination handling, settings retrieval, and reconciliation logic can be runtime-agnostic TypeScript. The pieces that read secrets from disk, integrate with a corporate identity provider, write audit exports, or invoke Node-specific scheduling libraries should be separated into Node-only modules in the consuming application. That separation mirrors the repository’s own constraints and makes it easier to reuse the same administrative workflow in Node.js, Deno, Workers, or edge environments when the surrounding platform supports secure secret storage.
Execution Flow for Directory and Settings Inventory
A typical compliance inventory run begins by constructing an SDK client with the correct Compliance Access Key in a secure server-side environment. The job then lists organizations under the parent organization associated with the key. For each returned organization, it can call the relevant directory endpoints to enumerate users, roles, groups, and group members, subject to the scopes on the key. Finally, it retrieves effective organization settings for each organization so the report reflects enforced policy rather than only configured or desired policy. The result is a normalized snapshot suitable for audit, reconciliation, or dashboard storage.
The effective settings endpoint is especially useful because it returns the current enforced state after all policies are applied. The official API reference describes GET /v1/compliance/organizations/{organization_id}/settings, with organization_id as a path parameter and an optional x-api-key header. The response includes the organization id, an array of settings, and compliance API key metadata such as key id, creation time, creator id, active state, name, scopes, and type. Key secret values are never included, which makes the response suitable for audit visibility without leaking credentials.
A robust implementation should treat 404 and 403 as different operational signals. An unknown organization or one outside the key’s hierarchy is documented as returning 404 for settings retrieval; an incorrect key type for compliance endpoints is documented as 403 Forbidden. Retry behavior should not blur these categories. Retrying a forbidden request will not fix a key-type problem, while a not-found response may indicate stale organization data, hierarchy drift, or an input bug. Administrative jobs should log enough context to distinguish those cases without storing sensitive key material or unnecessary user data.
Compact Reference
| Concept | Administrative meaning | Integration notes |
|---|---|---|
| Organization | Administrative boundary and hierarchy node | Compliance keys are bound to a parent organization and can reach linked organizations underneath it. |
| User | Identity within an organization | User and group-member endpoints require read:compliance_user_data. |
| Role | Permission definition within an organization | Useful for access reports and authorization reconciliation. |
| Group | RBAC or SCIM-provisioned membership container | Compare group membership against an external identity source of record. |
| Effective settings | Enforced organization policy state | Retrieved with GET /v1/compliance/organizations/{organization_id}/settings. |
| Workspace | Usage, key, member, and cost partition | API keys are scoped to a single workspace; workspace ids use the wrkspc_ prefix. |
| Claude Code workspace | Special workspace for Claude Code Console billing sign-in | Automatically created and managed differently from standard workspaces. |
Use read:compliance_org_data for organization, role, group, and settings reads, and use read:compliance_user_data where user data or group-member data is required. Keep Compliance Access Keys separate from Admin API keys in configuration, naming, and secret storage, because the API treats those key types differently. For SDK-based tools, prefer a backend runtime and keep browser execution disabled unless the broader application has an explicit, reviewed threat model. The SDK can detect browser and edge runtimes, but administrative credentials should still be handled as server-side secrets.
Implementation Guidance and Next Steps
Start by modeling the data you need before writing the request loop. If your goal is eDiscovery readiness, prioritize organizations, users, and group membership. If your goal is policy attestation, prioritize organizations plus effective settings. If your goal is cost governance or project-level access, use workspace concepts and keep them distinct from compliance directory snapshots. This upfront separation prevents a common failure mode where one job mixes audit inventory, workspace mutations, and credential metadata into an overprivileged integration that is difficult to reason about.
Next, choose a runtime and package boundary that matches the repository’s portability rules. In Node.js, keep local filesystem and process-specific code in application modules rather than shared SDK-facing logic. In edge or Worker deployments, rely on the platform’s secret store and avoid Node builtins entirely. If you publish a reusable internal package for administration, follow the same principle as the SDK: runtime-agnostic core modules, isolated Node-only adapters, and no hidden imports that surprise bundlers. That structure keeps compliance workflows testable and reduces deployment-specific breakage. Sources: CLAUDE.md
For deeper implementation work, continue with the Admin API and authentication pages for key creation and platform-management context, then read the request options and errors page before building production retries and observability. If your integration also governs usage allocation, pair this page with workspace documentation and any SDK resource reference page that covers Admin or beta administration surfaces in your version of the package.