Onecli Secrets API

openapi: 3.1.0
info:
  title: OneCLI Agent Setup 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: Secrets
  description: Manage credentials that the gateway injects into outbound requests.
paths:
  /secrets:
    get:
      operationId: listSecrets
      summary: List secrets
      description: Returns all secrets in the current project. Secret values are never returned.
      tags:
      - Secrets
      responses:
        '200':
          description: List of secrets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Secret'
    post:
      operationId: createSecret
      summary: Create a secret
      description: 'Creates a new secret. The gateway uses secrets to inject credentials into outbound requests matching the host and path patterns.


        - **anthropic** and **openai** types are auto-configured.

        - **generic** type requires an `injectionConfig`.

        - Instead of an inline `value`, a project secret can reference a 1Password field: set `valueSource` to `onepassword` and provide `opRef`. The gateway resolves the value at request time via the project''s 1Password vault connection.

        '
      tags:
      - Secrets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - type
              - hostPattern
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  example: Anthropic Production
                type:
                  type: string
                  enum:
                  - anthropic
                  - openai
                  - generic
                valueSource:
                  type: string
                  enum:
                  - inline
                  - onepassword
                  default: inline
                value:
                  type: string
                  minLength: 1
                  maxLength: 10000
                  description: The secret value (API key, token, etc.). Required unless `valueSource` is `onepassword`.
                opRef:
                  type: string
                  description: 1Password secret reference (`op://vault/item/field`). Required when `valueSource` is `onepassword`.
                opDisplay:
                  type: object
                  description: Human-readable labels of the picked 1Password vault/item/field, for display only.
                  properties:
                    vault:
                      type: string
                    item:
                      type: string
                    field:
                      type: string
                hostPattern:
                  type: string
                  description: Hostname pattern to match (no `://`, `/`, or spaces). A `*.` wildcard is only allowed as a leading subdomain and must not cover a public suffix.
                  example: api.anthropic.com
                pathPattern:
                  type: string
                  maxLength: 1000
                  description: Optional path pattern to match
                injectionConfig:
                  $ref: '#/components/schemas/InjectionConfig'
      responses:
        '201':
          description: Secret created. The response contains the core fields (`id`, `name`, `type`, `valueSource`, `opRef`, `hostPattern`, `pathPattern`, `createdAt`) plus a masked `preview` of inline values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretCreated'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /secrets/{secretId}:
    patch:
      operationId: updateSecret
      summary: Update a secret
      description: 'Updates one or more fields on a secret. At least one field must be provided.


        Set `valueSource` to `onepassword` (with `opRef`) to switch the secret to a 1Password-resolved value, or provide `value` to store an inline value.

        '
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/secretId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                valueSource:
                  type: string
                  enum:
                  - inline
                  - onepassword
                value:
                  type: string
                  minLength: 1
                  maxLength: 10000
                opRef:
                  type: string
                  description: 1Password secret reference (`op://vault/item/field`). Required when `valueSource` is `onepassword`.
                opDisplay:
                  type: object
                  properties:
                    vault:
                      type: string
                    item:
                      type: string
                    field:
                      type: string
                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'
        '404':
          description: Secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteSecret
      summary: Delete a secret
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/secretId'
      responses:
        '204':
          description: Secret deleted
        '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`