> ## 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. # Create an organization rule > Appended just above the Default Rule and enforced immediately. ## OpenAPI ````yaml /openapi.yaml post /org/policy/rules 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: /org/policy/rules: post: tags: - Organization policy summary: Create an organization rule description: Appended just above the Default Rule and enforced immediately. operationId: createOrgPolicyRule requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePolicyRuleInput' responses: '201': description: The rule content: application/json: schema: $ref: '#/components/schemas/PolicyRule' '403': description: >- A plan-gated modifier (rate limit, group identity) on a plan without it (Cloud), or a group identity without the Enterprise entitlement (self-hosted) content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Validation error (unpaired `rateLimit`/`rateLimitWindow`, a modifier on a `block` rule, no targets, resource scoping without a connection target) content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreatePolicyRuleInput: type: object description: >- A rule must name at least one target (an empty or missing `targets` list is refused with `422`). `rateLimit`/`rateLimitWindow` are paired and, like `requireApproval`, valid only with `action: allow`. On Cloud, `rateLimit` needs the Pro plan or above and `group` identities need the Enterprise plan; manual approval is available on every plan. required: - name - action - targets properties: name: type: string maxLength: 255 description: type: string maxLength: 1000 enabled: type: boolean default: true action: type: string enum: - allow - block rateLimit: type: integer minimum: 1 maximum: 1000000 rateLimitWindow: type: string enum: - minute - hour - day requireApproval: type: boolean conditions: description: >- A conditions array (max 10) or a session-policy object (`{repositories: [...]}` / `{folders: [...]}` / `{driveFolders: [...]}`; allow rules with a connection target only). identities: type: array maxItems: 100 items: $ref: '#/components/schemas/PolicyRuleIdentity' targets: type: array maxItems: 100 minItems: 1 items: $ref: '#/components/schemas/PolicyRuleTarget' PolicyRule: type: object description: >- A policy-engine rule. Every write is enforced immediately; the draft/published split survives only for older clients. Published row `id`s regenerate on every publish; `logicalId` is the identity stable across statuses and generations. properties: id: type: string scope: type: string enum: - organization - workspace status: type: string enum: - draft - published generation: type: integer description: >- 0 for the draft working copy; the snapshot number for published rows. priority: type: integer description: First-match order (lower evaluates first). enabled: type: boolean isDefault: type: boolean description: True on the scope's terminal Default Rule. logicalId: type: string description: >- Generation-stable identity; compare rules across draft/published by this, never by `id`. source: type: string description: >- `custom` (user-owned, editable), `default` (the Default Rule), or system-managed rows: `blocklist` (compiled from app blocklists) and, at workspace scope, `grant` (compiled from agent grants; managed through the Grants endpoints, never edited as rules). name: type: string description: type: string nullable: true action: type: string enum: - allow - block rateLimit: type: integer nullable: true rateLimitWindow: type: string nullable: true enum: - minute - hour - day - null requireApproval: type: boolean conditions: description: >- A conditions array, a session-policy object (`{repositories}` / `{folders}` / `{driveFolders}`), or null. nullable: true identities: type: array items: $ref: '#/components/schemas/PolicyRuleIdentity' targets: type: array items: $ref: '#/components/schemas/PolicyRuleTarget' createdAt: type: string format: date-time Error: description: > Error responses take one of two shapes depending on the failing layer: route-level validation returns the flat shape (`{ "error": "..." }`), while authentication failures and service errors return the envelope (`{ "error": { "message": "...", "type": "..." } }`). oneOf: - $ref: '#/components/schemas/ErrorFlat' - $ref: '#/components/schemas/ErrorEnvelope' PolicyRuleIdentity: type: object description: >- A principal the rule applies to. Organization rules take `user`/`group` identities (`agent` exists at workspace scope only). An empty identity list means the rule applies to everyone. Targeting a `group` is an Enterprise feature. required: - type - id properties: type: type: string enum: - agent - user - group id: type: string PolicyRuleTarget: type: object description: >- One destination the rule matches, a discriminated union on `kind`: an `app` target (provider, optionally narrowed by `tools`), a `connection` target (`connectionId`, optional `tools`), a `secret` target (a specific `secretId` XOR a `secretScope` level), or a `network` target (host/path/method patterns). A rule needs at least one target. required: - kind properties: kind: type: string enum: - app - connection - secret - network provider: type: string description: '`app` targets: the provider id (for example `gmail`).' tools: type: array maxItems: 100 items: type: string description: >- `app`/`connection` targets: narrow matching to these catalog tool ids; empty = the whole app. connectionScope: type: string enum: - organization - workspace nullable: true description: >- `app` targets: set = inject all the agent's connections of the provider at that level; `null` (or omitted on write) = a block/allow layer with no injection. connectionId: type: string description: '`connection` targets: the connection id.' secretId: type: string description: >- `secret` targets: a specific secret (mutually exclusive with `secretScope`). secretScope: type: string enum: - organization - workspace description: '`secret` targets: all the agent''s secrets at that level.' hostPattern: type: string maxLength: 1000 description: '`network` targets.' pathPattern: type: string nullable: true maxLength: 1000 method: type: string nullable: true enum: - GET - POST - PUT - PATCH - DELETE - null ErrorFlat: type: object description: Flat error shape used by route-level validation. required: - error properties: error: type: string ErrorEnvelope: type: object description: >- Envelope error shape used for authentication failures and service errors. properties: error: type: object properties: message: type: string type: type: string description: >- Error category: `authentication_error`, `invalid_request_error`, `not_found_error`, `validation_error`, `rate_limit_error`, `enterprise_license_required`, or `api_error`. code: type: string description: >- Present on some `401`s (for example when the organization requires SSO). 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.