> ## Documentation Index > Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # List workspaces in your organization > Returns the workspaces in your organization that you can see. Admins and owners see every workspace, while other members see only those shared with them. Returns every workspace visible to the caller, with no `X-Workspace-Id` needed. Use it to find the workspace id for later calls. See [Projects](https://onecli.sh/docs/guides/projects.md) for how workspaces divide an organization. The workspaces in the organization the caller can see. Admins and owners see every workspace; other members see the workspaces shared with them. No `X-Workspace-Id` is needed. `/v1/projects` is a deprecated alias of this path. > [!NOTE] > > **Availability:** Cloud · Community (self-hosted) · Enterprise (self-hosted) ## OpenAPI ````yaml /openapi.yaml get /workspaces openapi: 3.1.0 info: title: OneCLI API version: '1.0' description: > The OneCLI API manages everything behind the gateway: workspaces, agents and what each agent may use (grants), secrets, app connections, organization policy, hosted-agent conversations, schedules, memory, skills, Slack channels, and the organization's directory. **Base URL:** `https://api.onecli.sh/v1` (OneCLI Cloud) or `http://localhost:10254/v1` (self-hosted). ## Authentication Every endpoint takes an `Authorization: Bearer ` header unless its description says otherwise. - **Workspace API key** (`oc_…`) — acts inside one workspace. Read it from the dashboard or `GET /user/api-key`. - **Organization API key** (`oc_org_…`) — acts for the whole organization. Workspace-scoped endpoints additionally need an `X-Workspace-Id` header naming the workspace; without it they answer `401`. - **Dashboard session** — the browser's own session (Cloud: a bearer JWT; self-hosted: the session cookie). `X-Workspace-Id` replaced `X-Project-Id`. The old header, the `?_project` query bridge, and the `/v1/projects` path alias still work for a deprecation window and answer with a `Deprecation: true` header; migrate to the new names. ## Editions Each endpoint states where it is available. Unless marked otherwise an endpoint exists on **OneCLI Cloud**, the **Community** self-hosted edition, and the **Enterprise** self-hosted edition. Endpoints tagged **Enterprise** answer `403` with `error.type: "enterprise_license_required"` on a self-hosted deployment that has not set `ENTERPRISE_ENABLED=true`; on Cloud they are always present, though some features are additionally gated by the organization's plan. Endpoints tagged **Cloud** do not exist on self-hosted deployments at all. ## Roles Organization-level endpoints (`/org/…`) require the **admin** or **owner** role wherever roles are enforced (Cloud and Enterprise). The Community edition runs a flat team: every active member passes the role check. servers: - url: https://api.onecli.sh/v1 description: OneCLI Cloud - url: http://localhost:10254/v1 description: Self-hosted security: - bearerAuth: [] tags: - name: Workspaces description: >- Workspaces partition an organization's agents, secrets, and connections. Every workspace-scoped endpoint resolves its workspace from the API key (or `X-Workspace-Id` with an organization key). - name: Agents description: >- Manage agents, their gateway access tokens, and hosted-agent configuration. - name: Grants description: >- Which credentials each agent may use — attach app connections (with optional per-tool allow/approval lists and resource scoping) and secrets. Writes take effect immediately. - name: Secrets description: >- Credentials the gateway injects into outbound requests that match a host pattern. - name: Apps description: >- The app catalog, OAuth and direct-credential connects, your own OAuth client configuration, permission catalogs, and blocklists. - name: Connections description: Connected app accounts as a top-level resource. - name: Effective policy description: >- Read-only reflections of what the enforced policy means for an agent, a connection, or an app — workspace grants composed with organization rules. - name: Conversations description: >- Talk to a hosted agent. A conversation owns its turns, transcript, and attachments. - name: Schedules description: Cron-style schedules on a hosted agent. - name: Memories description: A hosted agent's memory files and their revision history. - name: Skills description: >- Skills reachable from a workspace — the organization's, the workspace's own, and per-agent ones. - name: Channels description: >- Where a hosted agent is reachable (Slack), who may reach it, who it may message, and which other agents it may talk to. - name: Approvals description: Long-poll for the gateway's manual-approval requests and submit decisions. - name: User description: Your profile, API keys, SSH keys, and account deletion. - name: Instance description: Unauthenticated deployment facts and bootstrap endpoints. - name: Utility description: Counts, vaults, and agent bootstrap helpers. - name: Organization description: The current organization and its invitations. Free on every edition. - name: Organization secrets description: Secrets shared into every workspace of the organization. - name: Organization policy description: >- The organization's first-match rule set — blocks, allows, rate limits, approvals, and app permissions that bind every workspace. - name: Organization connections description: App connections shared into every workspace of the organization. - name: Organization apps description: >- Connect apps and configure your own OAuth clients at the organization level. - name: Organization skills description: Skills every workspace in the organization receives. - name: Organization channels description: The organization's Slack integration and identity links. - name: Organization approvals description: Long-poll for manual-approval requests across every workspace. - name: Members description: The organization directory — list, provision, suspend, and remove members. - name: Groups description: Directory groups and group-to-role mappings. - name: Workspace access description: Share a workspace with people and groups. - name: Domains description: Verified email domains, the anchor for SSO and home-realm discovery. - name: SSO description: SAML and OIDC sign-in connections and organization-wide enforcement. - name: SCIM tokens description: Bearer tokens for the organization's SCIM endpoint. - name: App availability description: Restrict which apps each workspace may connect. - name: Provisioning description: >- Pre-create members with a ready workspace and API key, then let them claim the account. - name: Resource browsing description: Browse a connected account's folders to pick resource scopes for a grant. - name: SCIM description: >- The SCIM 2.0 provisioning endpoint for identity providers (Okta, Entra ID, and others). paths: /workspaces: get: tags: - Workspaces summary: List workspaces description: > The workspaces in the organization the caller can see. Admins and owners see every workspace; other members see the workspaces shared with them. No `X-Workspace-Id` is needed. `/v1/projects` is a deprecated alias of this path. operationId: listWorkspaces responses: '200': description: Workspaces, oldest first content: application/json: schema: type: array items: $ref: '#/components/schemas/Workspace' components: schemas: Workspace: type: object properties: id: type: string name: type: string slug: type: string createdAt: type: string format: date-time securitySchemes: bearerAuth: type: http scheme: bearer description: >- A workspace API key (`oc_…`) or organization API key (`oc_org_…`). Workspace-scoped endpoints called with an organization key also need `X-Workspace-Id`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.