IntegrationOS Vault API

openapi: 3.2.0
info:
  description: The One API. Universal API integration platform for AI agents and applications.
  license:
    name: ''
  title: One Vault API
  version: 5.35.0
tags:
- description: Manage vault connections with detailed views
  name: Vault
paths:
  /v1/vault/connections:
    get:
      description: Returns the connections you have access to. The result is filtered to your scope automatically — your own connections, your organization's, or your project's, depending on the key you use. Filter further by platform, identity, key, or tags.
      operationId: list_vault_connections
      parameters:
      - in: query
        name: page
        required: true
        schema:
          $ref: '#/components/schemas/Page'
      - description: 'Filter by the upstream platform identity (e.g. the user''s email

          or remote account id) the connection authenticates as.'
        in: query
        name: identity
        required: false
        schema:
          type: string
      - description: 'Restrict the result to connections of the given identity type

          (`user`, `account`, `workspace`, etc.).'
        in: query
        name: identityType
        required: false
        schema:
          $ref: '#/components/schemas/ConnectionIdentityType'
      - description: Filter by platform identifier (e.g. `gmail`, `shopify`).
        in: query
        name: platform
        required: false
        schema:
          type: string
      - description: 'Filter by exact connection key. Accepts a single key or a

          comma-separated list.'
        in: query
        name: key
        required: false
        schema:
          type: string
      - description: 'Filter by tags attached to the connection. Accepts a single tag

          or a comma-separated list.'
        in: query
        name: tags
        required: false
        schema:
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Organization-Id
        required: false
        schema:
          format: uuid
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Project-Id
        required: false
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated_VaultConnectionView'
          description: Paginated list of vault connections
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid connection credentials
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Connection not found
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream platform unavailable
      security:
      - X-One-Secret: []
      - OAuth2:
        - user:connections:read
      - OAuth2:
        - org:connections:read
      - OAuth2:
        - project:connections:read
      summary: List vault connections
      tags:
      - Vault
  /v1/vault/connections/{id}:
    delete:
      description: Permanently removes a connection and its stored credentials. Any future action or passthrough call using this connection will fail.
      operationId: delete_vault_connection
      parameters:
      - description: Connection ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Organization-Id
        required: false
        schema:
          format: uuid
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Project-Id
        required: false
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: Vault connection deleted
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid connection credentials
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Connection not found
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream platform unavailable
      security:
      - X-Pica-Secret: []
      - OAuth2:
        - user:connections:write
      - OAuth2:
        - org:connections:write
      - OAuth2:
        - project:connections:write
      summary: Delete vault connection
      tags:
      - Vault
    get:
      description: Returns the details of a single connection. Scoped automatically to your credential — you'll only see connections you have access to.
      operationId: retrieve_vault_connection
      parameters:
      - description: Connection ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Organization-Id
        required: false
        schema:
          format: uuid
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Project-Id
        required: false
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultConnectionView'
          description: Vault connection details
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid connection credentials
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Connection not found
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream platform unavailable
      security:
      - X-Pica-Secret: []
      - OAuth2:
        - user:connections:read
      - OAuth2:
        - org:connections:read
      - OAuth2:
        - project:connections:read
      summary: Retrieve vault connection
      tags:
      - Vault
    patch:
      description: Replaces the tags on a connection. The list you send becomes the new set — tags you omit are removed. Scoped automatically to your credential.
      operationId: update_vault_connection_tags
      parameters:
      - description: Connection ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Organization-Id
        required: false
        schema:
          format: uuid
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Project-Id
        required: false
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            example:
              tags:
              - production
              - billing
            schema:
              $ref: '#/components/schemas/UpdateConnection'
        required: true
      responses:
        '200':
          description: Vault connection tags updated
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid connection credentials
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Connection not found
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream platform unavailable
      security:
      - X-Pica-Secret: []
      - OAuth2:
        - user:connections:write
      - OAuth2:
        - org:connections:write
      - OAuth2:
        - project:connections:write
      summary: Update vault connection tags
      tags:
      - Vault
  /v1/vault/organizations/{org_id}/connections:
    get:
      description: Returns the connections inside an organization. Useful when an admin needs to see every connection across the org regardless of which project they're signed into. Filter by platform, identity, key, or tags.
      operationId: list_organization_vault_connections
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - in: query
        name: page
        required: true
        schema:
          $ref: '#/components/schemas/Page'
      - description: 'Filter by the upstream platform identity (e.g. the user''s email

          or remote account id) the connection authenticates as.'
        in: query
        name: identity
        required: false
        schema:
          type: string
      - description: 'Restrict the result to connections of the given identity type

          (`user`, `account`, `workspace`, etc.).'
        in: query
        name: identityType
        required: false
        schema:
          $ref: '#/components/schemas/ConnectionIdentityType'
      - description: Filter by platform identifier (e.g. `gmail`, `shopify`).
        in: query
        name: platform
        required: false
        schema:
          type: string
      - description: 'Filter by exact connection key. Accepts a single key or a

          comma-separated list.'
        in: query
        name: key
        required: false
        schema:
          type: string
      - description: 'Filter by tags attached to the connection. Accepts a single tag

          or a comma-separated list.'
        in: query
        name: tags
        required: false
        schema:
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Organization-Id
        required: false
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated_VaultConnectionView'
          description: Paginated list of organization vault connections
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid connection credentials
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Connection not found
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream platform unavailable
      security:
      - X-Pica-Secret: []
      - OAuth2:
        - org:connections:read
      summary: List organization vault connections
      tags:
      - Vault
  /v1/vault/organizations/{org_id}/connections/{id}:
    get:
      description: Returns the details of a single connection inside an organization, including its platform, identity, tags, and current status.
      operationId: retrieve_organization_vault_connection
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Connection ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Organization-Id
        required: false
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultConnectionView'
          description: Organization vault connection details
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid connection credentials
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Connection not found
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream platform unavailable
      security:
      - X-Pica-Secret: []
      - OAuth2:
        - org:connections:read
      summary: Retrieve organization vault connection
      tags:
      - Vault
  /v1/vault/organizations/{org_id}/projects/{project_id}/connections:
    get:
      description: Returns the connections inside a specific project. Useful when a caller with org-wide access needs to narrow to one project. Filter by platform, identity, key, or tags.
      operationId: list_project_vault_connections
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Project ID
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - in: query
        name: page
        required: true
        schema:
          $ref: '#/components/schemas/Page'
      - description: 'Filter by the upstream platform identity (e.g. the user''s email

          or remote account id) the connection authenticates as.'
        in: query
        name: identity
        required: false
        schema:
          type: string
      - description: 'Restrict the result to connections of the given identity type

          (`user`, `account`, `workspace`, etc.).'
        in: query
        name: identityType
        required: false
        schema:
          $ref: '#/components/schemas/ConnectionIdentityType'
      - description: Filter by platform identifier (e.g. `gmail`, `shopify`).
        in: query
        name: platform
        required: false
        schema:
          type: string
      - description: 'Filter by exact connection key. Accepts a single key or a

          comma-separated list.'
        in: query
        name: key
        required: false
        schema:
          type: string
      - description: 'Filter by tags attached to the connection. Accepts a single tag

          or a comma-separated list.'
        in: query
        name: tags
        required: false
        schema:
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Project-Id
        required: false
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated_VaultConnectionView'
          description: Paginated list of project vault connections
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid connection credentials
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Connection not found
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream platform unavailable
      security:
      - X-Pica-Secret: []
      - OAuth2:
        - project:connections:read
      summary: List project vault connections
      tags:
      - Vault
  /v1/vault/organizations/{org_id}/projects/{project_id}/connections/{id}:
    get:
      description: Returns the details of a single connection inside a project.
      operationId: retrieve_project_vault_connection
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Project ID
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Connection ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Selects the tenant this request acts in. Omit it to act in your personal scope.
        in: header
        name: X-One-Project-Id
        required: false
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultConnectionView'
          description: Project vault connection details
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid connection credentials
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Connection not found
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream platform unavailable
      security:
      - X-Pica-Secret: []
      - OAuth2:
        - project:connections:read
      summary: Retrieve project vault connection
      tags:
      - Vault
components:
  schemas:
    ConnectionStateType:
      enum:
      - operational
      - degraded
      - failed
      - unknown
      type: string
    UpdateConnection:
      properties:
        name:
          description: 'New display name for the connection. Empty string clears it;

            when omitted, the name is left untouched.'
          type:
          - string
          - 'null'
        tags:
          description: 'New tag set for the connection, checked by the shared tag check in

            the handler. When omitted, tags are left untouched.'
          items:
            type: string
          type:
          - array
          - 'null'
      type: object
    ErrorResponse:
      properties:
        correlationId:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        key:
          example: http_error
          type: string
        message:
          example: Authentication required
          type: string
        status:
          example: 401
          format: int32
          minimum: 0
          type: integer
        type:
          example: http_error
          type: string
      required:
      - correlationId
      - key
      - message
      - type
      - status
      type: object
    SecretKeyEnvironment:
      enum:
      - test
      - live
      type: string
    ConnectionIdentityType:
      enum:
      - organization
      - user
      - team
      - project
      type: string
    Paginated_VaultConnectionView:
      properties:
        page:
          format: int64
          minimum: 0
          type: integer
        pages:
          format: int64
          minimum: 0
          type: integer
        rows:
          items:
            properties:
              active:
                type: boolean
              connector:
                description: 'The connector behind this connection. Carried because a grant bounded

                  by connectors decides on it, so a caller rendering what a token may do

                  here would otherwise have to resolve it by a second lookup per row.'
                type: string
              description:
                type: string
              environment:
                $ref: '#/components/schemas/SecretKeyEnvironment'
              id:
                format: uuid
                type: string
              identity:
                type:
                - string
                - 'null'
              identityType:
                oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/ConnectionIdentityType'
              image:
                type: string
              key:
                type: string
              name:
                type:
                - string
                - 'null'
              platform:
                type: string
              platformVersion:
                type: string
              state:
                $ref: '#/components/schemas/ConnectionStateType'
              tags:
                items:
                  type: string
                type: array
              title:
                type:
                - string
                - 'null'
              type:
                $ref: '#/components/schemas/ConnectionType'
              version:
                type: string
            required:
            - id
            - connector
            - platformVersion
            - type
            - key
            - environment
            - platform
            - description
            - image
            - version
            - state
            - tags
            - active
            type: object
          type: array
        total:
          format: int64
          minimum: 0
          type: integer
      required:
      - rows
      - total
      - pages
      - page
      type: object
    VaultConnectionView:
      properties:
        active:
          type: boolean
        connector:
          description: 'The connector behind this connection. Carried because a grant bounded

            by connectors decides on it, so a caller rendering what a token may do

            here would otherwise have to resolve it by a second lookup per row.'
          type: string
        description:
          type: string
        environment:
          $ref: '#/components/schemas/SecretKeyEnvironment'
        id:
          format: uuid
          type: string
        identity:
          type:
          - string
          - 'null'
        identityType:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ConnectionIdentityType'
        image:
          type: string
        key:
          type: string
        name:
          type:
          - string
          - 'null'
        platform:
          type: string
        platformVersion:
          type: string
        state:
          $ref: '#/components/schemas/ConnectionStateType'
        tags:
          items:
            type: string
          type: array
        title:
          type:
          - string
          - 'null'
        type:
          $ref: '#/components/schemas/ConnectionType'
        version:
          type: string
      required:
      - id
      - connector
      - platformVersion
      - type
      - key
      - environment
      - platform
      - description
      - image
      - version
      - state
      - tags
      - active
      type: object
    Page:
      properties:
        limit:
          description: 'Items per page. Default 20, hard-capped at 150. `limit=0` is

            treated as 1. Larger values silently clamp.'
          format: int64
          minimum: 0
          type: integer
        page:
          description: Page number for pagination (1-indexed). Defaults to 1.
          format: int64
          minimum: 0
          type: integer
        skip:
          description: 'Number of items to skip before the first returned item. Defaults to 0.

            Most callers should leave this at 0 and rely on `page` + `limit`.'
          format: int64
          minimum: 0
          type: integer
      type: object
    ConnectionType:
      enum:
      - api
      - databasesql
      - databasenosql
      - filesystem
      - stream
      - custom
      type: string
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://api.withone.ai/oauth/authorize
          scopes:
            org:ai_skills:read: Read organization AI skills
            org:ai_skills:write: Create, update, and delete organization AI skills
            org:authkit:read: Read organization AuthKit resources
            org:authkit:write: Create, update, and delete organization AuthKit resources
            org:connections:read: Read organization connections
            org:connections:write: Create, update, and delete organization connections
            org:projects:read: Read organization projects
            org:projects:write: Create, update, and delete organization projects
            org:secrets:read: Read organization secrets
            org:secrets:write: Create, update, and delete organization secrets
            org:workflows:executions:read: Read organization workflow executions
            org:workflows:executions:write: Create, update, and delete organization workflow executions
            org:workflows:read: Read organization workflows
            org:workflows:write: Create, update, and delete organization workflows
            project:ai_skills:read: Read project AI skills
            project:ai_skills:write: Create, update, and delete project AI skills
            project:authkit:read: Read project AuthKit resources
            project:authkit:write: Create, update, and delete project AuthKit resources
            project:connections:read: Read project connections
            project:connections:write: Create, update, and delete project connections
            project:secrets:read: Read project secrets
            project:secrets:write: Create, update, and delete project secrets
            project:workflows:executions:read: Read project workflow executions
            project:workflows:executions:write: Create, update, and delete project workflow executions
            project:workflows:read: Read project workflows
            project:workflows:write: Create, update, and delete project workflows
            user:ai_skills:read: Read your personal AI skills
            user:ai_skills:write: Create, update, and delete your personal AI skills
            user:authkit:read: Read your personal AuthKit resources
            user:authkit:write: Create, update, and delete your personal AuthKit resources
            user:connections:read: Read your personal connections
            user:connections:write: Create, update, and delete your personal connections
            user:secrets:read: Read your personal secrets
            user:

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/integration-os/refs/heads/main/openapi/integration-os-vault-api-openapi.yml