Onecli Organization Secrets API

openapi: 3.1.0
info:
  title: OneCLI Agent Setup Organization Secrets API
  version: '1.0'
  description: 'The OneCLI API lets you manage agents, secrets, policy rules, app connections, and user settings programmatically.


    **Base URL:** `https://api.onecli.sh/v1` (Cloud) or `http://localhost:10254/v1` (self-hosted)


    ## Authentication


    All endpoints require authentication via one of:


    - **API Key** — `Authorization: Bearer <key>` header. Generate keys in the dashboard or via `GET /v1/user/api-key`.

    - **Session** — Cookie-based session from the web dashboard.


    For organization-scoped API keys, include the `X-Project-Id` header to specify which project to operate on.

    '
servers:
- url: https://api.onecli.sh/v1
  description: OneCLI Cloud
- url: http://localhost:10254/v1
  description: Self-hosted (Docker)
security:
- bearerAuth: []
tags:
- name: Organization Secrets
  description: Manage secrets at the organization level. Organization secrets apply across all projects. Available on OneCLI Cloud and self-hosted Enterprise.
paths:
  /org/secrets:
    get:
      operationId: listOrgSecrets
      summary: List organization secrets
      description: Returns all secrets scoped to the organization. Secret values are never returned. Available on OneCLI Cloud and self-hosted Enterprise. Requires the admin or owner role.
      tags:
      - Organization Secrets
      responses:
        '200':
          description: List of organization secrets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Secret'
    post:
      operationId: createOrgSecret
      summary: Create an organization secret
      description: 'Creates a new secret at the organization level. Organization secrets apply across all projects. Requires admin role. Available on OneCLI Cloud and self-hosted Enterprise.


        1Password-sourced values (`valueSource: onepassword`) are project-only and rejected here — organization secrets must carry an inline `value`.

        '
      tags:
      - Organization Secrets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - type
              - value
              - hostPattern
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  example: Shared Anthropic Key
                type:
                  type: string
                  enum:
                  - anthropic
                  - openai
                  - generic
                value:
                  type: string
                  minLength: 1
                  maxLength: 10000
                  description: The secret value (API key, token, etc.)
                hostPattern:
                  type: string
                  description: Hostname pattern to match
                  example: api.anthropic.com
                pathPattern:
                  type: string
                  maxLength: 1000
                injectionConfig:
                  $ref: '#/components/schemas/InjectionConfig'
      responses:
        '201':
          description: Secret created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretCreated'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions (requires admin role)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /org/secrets/{secretId}:
    patch:
      operationId: updateOrgSecret
      summary: Update an organization secret
      description: Updates one or more fields on an organization secret. Requires admin role. Available on OneCLI Cloud and self-hosted Enterprise.
      tags:
      - Organization Secrets
      parameters:
      - $ref: '#/components/parameters/secretId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                value:
                  type: string
                  minLength: 1
                  maxLength: 10000
                hostPattern:
                  type: string
                pathPattern:
                  type: string
                  nullable: true
                injectionConfig:
                  $ref: '#/components/schemas/InjectionConfig'
      responses:
        '200':
          description: Secret updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '400':
          description: Validation error or no fields provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteOrgSecret
      summary: Delete an organization secret
      description: Requires admin role. Available on OneCLI Cloud and self-hosted Enterprise.
      tags:
      - Organization Secrets
      parameters:
      - $ref: '#/components/parameters/secretId'
      responses:
        '204':
          description: Secret deleted
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    InjectionConfig:
      nullable: true
      description: 'How the gateway injects this secret into matching outbound requests (generic secrets only). Exactly one variant:


        - **Header** — `{ "headerName": "Authorization", "valueFormat": "Bearer {value}" }`

        - **Query parameter** — `{ "paramName": "key", "paramFormat": "{value}" }`

        - **URL path template** — `{ "pathTemplate": "/bot{value}" }` (must start with `/` and contain `{value}` exactly once)

        - **URL path regex** — `{ "pathRegex": "^/bot([^/]+)", "pathReplacement": "/bot{value}" }` (replacement must contain `{value}`)


        Unknown or mixed keys are rejected.

        '
      oneOf:
      - type: object
        title: Header injection
        required:
        - headerName
        properties:
          headerName:
            type: string
            minLength: 1
          valueFormat:
            type: string
            description: 'Value template; `{value}` is replaced with the secret (default: `{value}`).'
        additionalProperties: false
      - type: object
        title: Query parameter injection
        required:
        - paramName
        properties:
          paramName:
            type: string
            minLength: 1
          paramFormat:
            type: string
            description: 'Value template; `{value}` is replaced with the secret (default: `{value}`).'
        additionalProperties: false
      - type: object
        title: URL path template injection
        required:
        - pathTemplate
        properties:
          pathTemplate:
            type: string
            description: Path with a `{value}` hole, e.g. `/bot{value}`. Must start with `/` and contain `{value}` exactly once.
        additionalProperties: false
      - type: object
        title: URL path regex injection
        required:
        - pathRegex
        - pathReplacement
        properties:
          pathRegex:
            type: string
            description: Regular expression matched against the request path.
          pathReplacement:
            type: string
            description: Replacement with `$N` capture references and a `{value}` token for the secret.
        additionalProperties: false
    SecretCreated:
      type: object
      description: The narrowed secret representation returned by create endpoints.
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        valueSource:
          type: string
          enum:
          - inline
          - onepassword
        opRef:
          type: string
        hostPattern:
          type: string
        pathPattern:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        preview:
          type: string
          description: Masked preview of the value (inline secrets only).
    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 (401/403) and service errors (not-found,

        conflict, and service-level validation) return the envelope

        (`{ "error": { "message": "...", "type": "..." } }`).

        '
      oneOf:
      - $ref: '#/components/schemas/ErrorFlat'
      - $ref: '#/components/schemas/ErrorEnvelope'
    ErrorFlat:
      type: object
      description: Flat error shape used by route-level validation.
      properties:
        error:
          type: string
      required:
      - error
    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 (e.g. `authentication_error`).
    Secret:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
          - anthropic
          - openai
          - generic
        valueSource:
          type: string
          enum:
          - inline
          - onepassword
          description: Where the secret value lives — stored encrypted (`inline`) or resolved from 1Password at request time (`onepassword`).
        opRef:
          type: string
          nullable: true
          description: 1Password secret reference (`op://vault/item/field`). Only set when `valueSource` is `onepassword`.
        hostPattern:
          type: string
        pathPattern:
          type: string
          nullable: true
        injectionConfig:
          $ref: '#/components/schemas/InjectionConfig'
        metadata:
          type: object
          nullable: true
          description: Type-specific metadata (e.g. `authMode` for `anthropic`/`openai` secrets, 1Password display labels).
        scope:
          type: string
          enum:
          - project
          - organization
          description: Project lists include inherited organization secrets; use this to tell them apart.
        typeLabel:
          type: string
        createdAt:
          type: string
          format: date-time
  parameters:
    secretId:
      name: secretId
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from the dashboard or `GET /user/api-key`