Kernel Credential Providers API

openapi: 3.2.0
info:
  description: Developer tools and cloud infrastructure for AI agents to use web browsers
  title: Kernel Credential Providers API
  version: 0.1.0
servers:
- description: API Server
  url: https://api.onkernel.com
security:
- bearerAuth: []
tags:
- description: Configure external credential providers like 1Password.
  name: Credential Providers
paths:
  /org/credential_providers:
    get:
      description: List external credential providers configured for the organization.
      operationId: getCredentialProviders
      parameters:
      - description: Limit the number of credential providers to return.
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - description: Offset the number of credential providers to return.
        in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: Case-insensitive substring match against credential provider name. IDs match by exact value.
        in: query
        name: query
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CredentialProvider'
                type: array
          description: List of credential providers
          headers:
            X-Has-More:
              description: Whether there are more credential providers to fetch.
              schema:
                default: false
                type: boolean
            X-Limit:
              description: Limit the number of credential providers to return.
              schema:
                default: 20
                maximum: 100
                minimum: 1
                type: integer
            X-Next-Offset:
              description: The offset where the next page starts. 0 when there are no more results.
              schema:
                nullable: true
                type: integer
            X-Offset:
              description: The offset of credential providers to return.
              schema:
                default: 0
                minimum: 0
                type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: List credential providers
      tags:
      - Credential Providers
      x-hidden: true
    post:
      description: Configure an external credential provider (e.g., 1Password) for automatic credential lookup.
      operationId: postCredentialProviders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCredentialProviderRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialProvider'
          description: Credential provider created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Create a credential provider
      tags:
      - Credential Providers
      x-hidden: true
  /org/credential_providers/{id}:
    delete:
      description: Delete a credential provider by its ID.
      operationId: deleteCredentialProvidersById
      parameters:
      - description: Credential provider ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Credential provider deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Delete credential provider
      tags:
      - Credential Providers
      x-hidden: true
    get:
      description: Retrieve a credential provider by its ID.
      operationId: getCredentialProvidersById
      parameters:
      - description: Credential provider ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialProvider'
          description: Credential provider details
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Get credential provider by ID
      tags:
      - Credential Providers
      x-hidden: true
    patch:
      description: Update a credential provider's configuration.
      operationId: patchCredentialProvidersById
      parameters:
      - description: Credential provider ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCredentialProviderRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialProvider'
          description: Credential provider updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Update credential provider
      tags:
      - Credential Providers
      x-hidden: true
  /org/credential_providers/{id}/items:
    get:
      description: Returns available credential items (e.g., 1Password login items) from the provider.
      operationId: getCredentialProviderItems
      parameters:
      - description: Credential provider ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/CredentialProviderItem'
                    type: array
                type: object
          description: List of credential items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: List items from a credential provider
      tags:
      - Credential Providers
      x-hidden: true
  /org/credential_providers/{id}/test:
    post:
      description: Validate the credential provider's token and list accessible vaults.
      operationId: testCredentialProviderById
      parameters:
      - description: Credential provider ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialProviderTestResult'
          description: Connection test successful
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Test credential provider connection
      tags:
      - Credential Providers
      x-hidden: true
components:
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Resource not found
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad Request – invalid input
    Conflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Conflict – resource already exists
    InternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal Server Error
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Forbidden – insufficient permissions or plan
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Unauthorized – missing or invalid authorization token
  schemas:
    UpdateCredentialProviderRequest:
      additionalProperties: false
      description: Request to update a credential provider
      properties:
        cache_ttl_seconds:
          description: How long to cache credential lists
          example: 300
          type: integer
        enabled:
          description: Whether the provider is enabled for credential lookups
          example: true
          type: boolean
        name:
          description: Human-readable name for this provider instance. Surrounding whitespace is trimmed and the trimmed value must be non-empty.
          example: my-1password
          minLength: 1
          pattern: \S
          type: string
        priority:
          description: Priority order for credential lookups (lower numbers are checked first)
          example: 0
          type: integer
        token:
          description: New service account token (to rotate credentials)
          example: ops_eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
          type: string
      type: object
    CredentialProvider:
      additionalProperties: false
      description: An external credential provider (e.g., 1Password) for automatic credential lookup
      properties:
        created_at:
          description: When the credential provider was created
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        enabled:
          description: Whether the provider is enabled for credential lookups
          example: true
          type: boolean
        id:
          description: Unique identifier for the credential provider
          example: credprov_abc123xyz
          type: string
        name:
          description: Human-readable name for this provider instance
          example: my-1password
          type: string
        priority:
          description: Priority order for credential lookups (lower numbers are checked first)
          example: 0
          type: integer
        provider_type:
          description: Type of credential provider
          enum:
          - onepassword
          example: onepassword
          type: string
        updated_at:
          description: When the credential provider was last updated
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
      required:
      - id
      - provider_type
      - name
      - enabled
      - priority
      - created_at
      - updated_at
      type: object
    CreateCredentialProviderRequest:
      additionalProperties: false
      description: Request to create an external credential provider
      properties:
        cache_ttl_seconds:
          default: 300
          description: How long to cache credential lists (default 300 seconds)
          example: 300
          type: integer
        name:
          description: Human-readable name for this provider instance (unique per org). Surrounding whitespace is trimmed and the trimmed value must be non-empty.
          example: my-1password
          minLength: 1
          pattern: \S
          type: string
        provider_type:
          description: Type of credential provider
          enum:
          - onepassword
          example: onepassword
          type: string
        token:
          description: Service account token for the provider (e.g., 1Password service account token)
          example: ops_eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
          type: string
      required:
      - provider_type
      - name
      - token
      type: object
    CredentialProviderTestResult:
      additionalProperties: false
      description: Result of testing a credential provider connection
      properties:
        error:
          description: Error message if the test failed
          example: Invalid token
          type: string
        success:
          description: Whether the connection test was successful
          example: true
          type: boolean
        vaults:
          description: List of vaults accessible by the service account
          items:
            properties:
              id:
                description: Vault ID
                example: abc123xyz
                type: string
              name:
                description: Vault name
                example: Shared Logins
                type: string
            required:
            - id
            - name
            type: object
          type: array
      required:
      - success
      - vaults
      type: object
    ErrorDetail:
      properties:
        code:
          description: Lower-level error code providing more specific detail
          example: invalid_input
          type: string
        message:
          description: Further detail about the error
          example: Provided version string is not semver compliant
          type: string
      type: object
    Error:
      properties:
        code:
          description: Application-specific error code (machine-readable)
          example: bad_request
          type: string
        details:
          description: Additional error details (for multiple errors)
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        inner_error:
          $ref: '#/components/schemas/ErrorDetail'
        message:
          description: Human-readable error description for debugging
          example: 'Missing required field: app_name'
          type: string
      required:
      - code
      - message
      type: object
    CredentialProviderItem:
      additionalProperties: false
      description: A credential item from an external provider (e.g., a 1Password login item)
      properties:
        id:
          description: Unique identifier for the item within the provider
          example: abc123xyz
          type: string
        path:
          description: Path to reference this item (VaultName/ItemTitle format)
          example: Engineering/Netflix Login
          type: string
        title:
          description: Display name of the credential item
          example: Netflix Login
          type: string
        urls:
          description: URLs associated with this credential
          example:
          - https://netflix.com
          - https://www.netflix.com
          items:
            type: string
          type: array
        vault_id:
          description: ID of the vault containing this item
          example: vault_abc123
          type: string
        vault_name:
          description: Name of the vault containing this item
          example: Engineering
          type: string
      required:
      - id
      - title
      - vault_id
      - vault_name
      - path
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
x-service-info:
  categories:
  - browsers
  docs:
    apiReference: https://www.kernel.sh/docs
    homepage: https://www.kernel.sh
    llms: https://api.onkernel.com/llms.txt
x-provenance:
  method: harvested
  publisher: Kernel
  source: https://api.onkernel.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)