Kernel Credentials API

openapi: 3.2.0
info:
  description: Developer tools and cloud infrastructure for AI agents to use web browsers
  title: Kernel Credentials API
  version: 0.1.0
servers:
- description: API Server
  url: https://api.onkernel.com
security:
- bearerAuth: []
tags:
- description: Create and manage credentials for authentication.
  name: Credentials
paths:
  /credentials:
    get:
      description: List credentials in the resolved project. Credential values are not returned.
      operationId: getCredentials
      parameters:
      - description: Filter by domain
        in: query
        name: domain
        required: false
        schema:
          type: string
      - description: Maximum number of results to return
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          type: integer
      - description: Number of results to skip
        in: query
        name: offset
        required: false
        schema:
          default: 0
          type: integer
      - description: Case-insensitive substring match against credential name or domain. IDs match by exact value.
        in: query
        name: query
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Credential'
                type: array
          description: List of credentials
          headers:
            X-Has-More:
              description: Whether there are more results
              schema:
                type: boolean
            X-Next-Offset:
              description: The offset where the next page starts. 0 when there are no more results.
              schema:
                type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: List credentials
      tags:
      - Credentials
      x-hidden: true
    post:
      description: Create a new credential for storing login information.
      operationId: postCredentials
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCredentialRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
          description: Credential 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
      tags:
      - Credentials
      x-hidden: true
  /credentials/{id_or_name}:
    delete:
      description: Delete a credential by its ID or name.
      operationId: deleteCredentialByIdOrName
      parameters:
      - description: Credential ID or name
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Credential 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
      tags:
      - Credentials
      x-hidden: true
    get:
      description: Retrieve a credential by its ID or name. Credential values are not returned.
      operationId: getCredentialByIdOrName
      parameters:
      - description: Credential ID or name
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
          description: Credential details
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Get credential by ID or name
      tags:
      - Credentials
      x-hidden: true
    patch:
      description: Update a credential's name or values. When values are provided, they are merged with existing values (new keys are added, existing keys are overwritten).
      operationId: patchCredentialByIdOrName
      parameters:
      - description: Credential ID or name
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCredentialRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
          description: Credential 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
      tags:
      - Credentials
      x-hidden: true
  /credentials/{id_or_name}/totp-code:
    get:
      description: Returns the current 6-digit TOTP code for a credential with a configured totp_secret. Use this to complete 2FA setup on sites or when you need a fresh code.
      operationId: getCredentialTotpCodeByIdOrName
      parameters:
      - description: Credential ID or name
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Current 6-digit TOTP code
                    example: '847291'
                    type: string
                  expires_at:
                    description: When this code expires (ISO 8601 timestamp)
                    example: '2025-01-15T10:30:30Z'
                    format: date-time
                    type: string
                required:
                - code
                - expires_at
                type: object
          description: TOTP code generated successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Credential not found or has no TOTP secret configured
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Generate TOTP code
      tags:
      - Credentials
      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:
    CreateCredentialRequest:
      additionalProperties: false
      description: Request to create a new credential
      properties:
        domain:
          description: Target domain this credential is for
          example: netflix.com
          type: string
        name:
          description: Unique name for the credential within the project
          example: my-netflix-login
          type: string
        sso_provider:
          description: If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page.
          example: google
          type: string
        totp_algorithm:
          description: HMAC algorithm used to generate TOTP codes. Defaults to SHA1 and is ignored when an `otpauth://` URI supplies the algorithm.
          enum:
          - SHA1
          - SHA256
          - SHA512
          example: SHA1
          type: string
        totp_digits:
          description: Number of digits in generated TOTP codes. Defaults to 6 and is ignored when an `otpauth://` URI supplies the digit count.
          example: 6
          maximum: 9
          minimum: 6
          type: integer
        totp_period:
          description: TOTP rotation period in seconds. Defaults to 30 and is ignored when an `otpauth://` URI supplies the period.
          example: 30
          maximum: 300
          minimum: 15
          type: integer
        totp_secret:
          description: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...` URI. The range accepts existing shorter seeds and longer seeds regardless of HMAC algorithm; RFC 6238 recommends unpadded base32 lengths of 32/52/103 for SHA1/SHA256/SHA512. Only URI parameters present override the corresponding explicit TOTP fields. Used for automatic 2FA during login.
          example: JBSWY3DPEHPK3PXP
          type: string
        values:
          additionalProperties:
            type: string
          description: Field name to value mapping (e.g., username, password)
          example:
            password: mysecretpassword
            username: user@example.com
          type: object
      required:
      - name
      - domain
      - values
      type: object
    Credential:
      additionalProperties: false
      description: A stored credential for automatic re-authentication
      properties:
        created_at:
          description: When the credential was created
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        domain:
          description: Target domain this credential is for
          example: netflix.com
          type: string
        has_totp_secret:
          description: Whether this credential has a TOTP secret configured for automatic 2FA
          example: false
          type: boolean
        has_values:
          description: Whether this credential has stored values (email, password, etc.)
          example: true
          type: boolean
        id:
          description: Unique identifier for the credential
          example: cred_abc123xyz
          type: string
        name:
          description: Unique name for the credential within the project
          example: my-netflix-login
          type: string
        sso_provider:
          description: If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page.
          example: google
          nullable: true
          type: string
        totp_algorithm:
          description: HMAC algorithm used to generate TOTP codes. Defaults to SHA1 for credentials created before this metadata was stored.
          enum:
          - SHA1
          - SHA256
          - SHA512
          example: SHA1
          type: string
        totp_code:
          description: Current TOTP code. Only included in create/update responses when totp_secret was just set.
          example: '847291'
          type: string
        totp_code_expires_at:
          description: When the totp_code expires. Only included when totp_code is present.
          example: '2025-01-15T10:30:30Z'
          format: date-time
          type: string
        totp_digits:
          description: Number of digits in generated TOTP codes. Defaults to 6 for credentials created before this metadata was stored.
          example: 6
          maximum: 9
          minimum: 6
          type: integer
        totp_period:
          description: TOTP rotation period in seconds. Defaults to 30 for credentials created before this metadata was stored.
          example: 30
          maximum: 300
          minimum: 15
          type: integer
        updated_at:
          description: When the credential was last updated
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        value_keys:
          description: The field names stored in this credential's values (e.g., username, password). Values themselves are never returned. Included on single-credential responses (create, get by id or name, update); omitted from list responses.
          example:
          - username
          - password
          items:
            type: string
          type: array
      required:
      - id
      - name
      - domain
      - created_at
      - updated_at
      type: object
    UpdateCredentialRequest:
      additionalProperties: false
      description: Request to update an existing credential
      properties:
        name:
          description: New name for the credential
          example: my-updated-login
          type: string
        remove_value_keys:
          description: Field names to remove from the credential's stored values. Removals are applied before `values` are merged, so a key present in both is kept with its new value.
          example:
          - old_field
          items:
            type: string
          type: array
        sso_provider:
          description: If set, indicates this credential should be used with the specified SSO provider. Set to empty string or null to remove.
          example: google
          nullable: true
          type: string
        totp_algorithm:
          description: HMAC algorithm used to generate TOTP codes. Requires totp_secret and is ignored when an `otpauth://` URI supplies the algorithm.
          enum:
          - SHA1
          - SHA256
          - SHA512
          example: SHA1
          type: string
        totp_digits:
          description: Number of digits in generated TOTP codes. Requires totp_secret and is ignored when an `otpauth://` URI supplies the digit count.
          example: 6
          maximum: 9
          minimum: 6
          type: integer
        totp_period:
          description: TOTP rotation period in seconds. Requires totp_secret and is ignored when an `otpauth://` URI supplies the period.
          example: 30
          maximum: 300
          minimum: 15
          type: integer
        totp_secret:
          description: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...` URI. Only URI parameters present override the corresponding explicit TOTP fields. When rotating a raw secret, omitted fields preserve their existing values; a new URI defaults unspecified fields to SHA1/6/30. Set to empty string to remove the secret and its metadata.
          example: JBSWY3DPEHPK3PXP
          type: string
        values:
          additionalProperties:
            type: string
          description: Field name to value mapping. Values are merged with existing values (new keys added, existing keys overwritten).
          example:
            password: newpassword
            username: user@example.com
          type: object
      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
  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)