openapi: 3.1.0
info:
  title: Kernel API Keys Credentials API
  description: Developer tools and cloud infrastructure for AI agents to use web browsers
  version: 0.1.0
servers:
- url: https://api.onkernel.com
  description: API Server
security:
- bearerAuth: []
tags:
- name: Credentials
  description: Create and manage credentials for authentication.
paths:
  /credentials:
    post:
      x-hidden: true
      operationId: postCredentials
      tags:
      - Credentials
      summary: Create a credential
      description: Create a new credential for storing login information.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCredentialRequest'
      responses:
        '201':
          description: Credential created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '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'
      x-codeSamples:
      - lang: JavaScript
        source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n  apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst credential = await client.credentials.create({\n  domain: 'netflix.com',\n  name: 'my-netflix-login',\n  values: { username: 'user@example.com', password: 'mysecretpassword' },\n});\n\nconsole.log(credential.id);"
      - lang: Python
        source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n    api_key=os.environ.get(\"KERNEL_API_KEY\"),  # This is the default and can be omitted\n)\ncredential = client.credentials.create(\n    domain=\"netflix.com\",\n    name=\"my-netflix-login\",\n    values={\n        \"username\": \"user@example.com\",\n        \"password\": \"mysecretpassword\",\n    },\n)\nprint(credential.id)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcredential, err := client.Credentials.New(context.TODO(), kernel.CredentialNewParams{\n\t\tCreateCredentialRequest: kernel.CreateCredentialRequestParam{\n\t\t\tDomain: \"netflix.com\",\n\t\t\tName:   \"my-netflix-login\",\n\t\t\tValues: map[string]string{\n\t\t\t\t\"username\": \"user@example.com\",\n\t\t\t\t\"password\": \"mysecretpassword\",\n\t\t\t},\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", credential.ID)\n}\n"
    get:
      x-hidden: true
      operationId: getCredentials
      tags:
      - Credentials
      summary: List credentials
      description: List credentials owned by the caller's organization. Credential values are not returned.
      security:
      - bearerAuth: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          type: string
        description: Filter by domain
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
        description: Maximum number of results to return
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        description: Number of results to skip
      responses:
        '200':
          description: List of credentials
          headers:
            X-Has-More:
              schema:
                type: boolean
              description: Whether there are more results
            X-Next-Offset:
              schema:
                type: integer
              description: Offset for next page
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Credential'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
      - lang: JavaScript
        source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n  apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const credential of client.credentials.list()) {\n  console.log(credential.id);\n}"
      - lang: Python
        source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n    api_key=os.environ.get(\"KERNEL_API_KEY\"),  # This is the default and can be omitted\n)\npage = client.credentials.list()\npage = page.items[0]\nprint(page.id)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Credentials.List(context.TODO(), kernel.CredentialListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
  /credentials/{id_or_name}:
    get:
      x-hidden: true
      operationId: getCredentialByIdOrName
      tags:
      - Credentials
      summary: Get credential by ID or name
      description: Retrieve a credential by its ID or name. Credential values are not returned.
      security:
      - bearerAuth: []
      parameters:
      - name: id_or_name
        in: path
        required: true
        schema:
          type: string
        description: Credential ID or name
      responses:
        '200':
          description: Credential details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
      - lang: JavaScript
        source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n  apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst credential = await client.credentials.retrieve('id_or_name');\n\nconsole.log(credential.id);"
      - lang: Python
        source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n    api_key=os.environ.get(\"KERNEL_API_KEY\"),  # This is the default and can be omitted\n)\ncredential = client.credentials.retrieve(\n    \"id_or_name\",\n)\nprint(credential.id)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcredential, err := client.Credentials.Get(context.TODO(), \"id_or_name\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", credential.ID)\n}\n"
    patch:
      x-hidden: true
      operationId: patchCredentialByIdOrName
      tags:
      - Credentials
      summary: Update credential
      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).
      security:
      - bearerAuth: []
      parameters:
      - name: id_or_name
        in: path
        required: true
        schema:
          type: string
        description: Credential ID or name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCredentialRequest'
      responses:
        '200':
          description: Credential updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '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'
      x-codeSamples:
      - lang: JavaScript
        source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n  apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst credential = await client.credentials.update('id_or_name');\n\nconsole.log(credential.id);"
      - lang: Python
        source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n    api_key=os.environ.get(\"KERNEL_API_KEY\"),  # This is the default and can be omitted\n)\ncredential = client.credentials.update(\n    id_or_name=\"id_or_name\",\n)\nprint(credential.id)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcredential, err := client.Credentials.Update(\n\t\tcontext.TODO(),\n\t\t\"id_or_name\",\n\t\tkernel.CredentialUpdateParams{\n\t\t\tUpdateCredentialRequest: kernel.UpdateCredentialRequestParam{},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", credential.ID)\n}\n"
    delete:
      x-hidden: true
      operationId: deleteCredentialByIdOrName
      tags:
      - Credentials
      summary: Delete credential
      description: Delete a credential by its ID or name.
      security:
      - bearerAuth: []
      parameters:
      - name: id_or_name
        in: path
        required: true
        schema:
          type: string
        description: Credential ID or name
      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'
      x-codeSamples:
      - lang: JavaScript
        source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n  apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.credentials.delete('id_or_name');"
      - lang: Python
        source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n    api_key=os.environ.get(\"KERNEL_API_KEY\"),  # This is the default and can be omitted\n)\nclient.credentials.delete(\n    \"id_or_name\",\n)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Credentials.Delete(context.TODO(), \"id_or_name\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
  /credentials/{id_or_name}/totp-code:
    get:
      x-hidden: true
      operationId: getCredentialTotpCodeByIdOrName
      tags:
      - Credentials
      summary: Generate TOTP code
      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.
      security:
      - bearerAuth: []
      parameters:
      - name: id_or_name
        in: path
        required: true
        schema:
          type: string
        description: Credential ID or name
      responses:
        '200':
          description: TOTP code generated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - expires_at
                properties:
                  code:
                    type: string
                    description: Current 6-digit TOTP code
                    example: '847291'
                  expires_at:
                    type: string
                    format: date-time
                    description: When this code expires (ISO 8601 timestamp)
                    example: '2025-01-15T10:30:30Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Credential not found or has no TOTP secret configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
      - lang: JavaScript
        source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n  apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.credentials.totpCode('id_or_name');\n\nconsole.log(response.code);"
      - lang: Python
        source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n    api_key=os.environ.get(\"KERNEL_API_KEY\"),  # This is the default and can be omitted\n)\nresponse = client.credentials.totp_code(\n    \"id_or_name\",\n)\nprint(response.code)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Credentials.TotpCode(context.TODO(), \"id_or_name\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Code)\n}\n"
components:
  responses:
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden – insufficient permissions or plan
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict – resource already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized – missing or invalid authorization token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request – invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CreateCredentialRequest:
      type: object
      description: Request to create a new credential
      required:
      - name
      - domain
      - values
      properties:
        name:
          type: string
          description: Unique name for the credential within the project
          example: my-netflix-login
        domain:
          type: string
          description: Target domain this credential is for
          example: netflix.com
        values:
          type: object
          description: Field name to value mapping (e.g., username, password)
          additionalProperties:
            type: string
          example:
            username: user@example.com
            password: mysecretpassword
        totp_secret:
          type: string
          description: Base32-encoded TOTP secret for generating one-time passwords. Used for automatic 2FA during login.
          example: JBSWY3DPEHPK3PXP
        sso_provider:
          type: string
          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
      additionalProperties: false
    ErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Lower-level error code providing more specific detail
          example: invalid_input
        message:
          type: string
          description: Further detail about the error
          example: Provided version string is not semver compliant
    UpdateCredentialRequest:
      type: object
      description: Request to update an existing credential
      properties:
        name:
          type: string
          description: New name for the credential
          example: my-updated-login
        values:
          type: object
          description: Field name to value mapping. Values are merged with existing values (new keys added, existing keys overwritten).
          additionalProperties:
            type: string
          example:
            username: user@example.com
            password: newpassword
        totp_secret:
          type: string
          description: Base32-encoded TOTP secret for generating one-time passwords. Spaces and formatting are automatically normalized. Set to empty string to remove.
          example: JBSWY3DPEHPK3PXP
        sso_provider:
          type: string
          nullable: true
          description: If set, indicates this credential should be used with the specified SSO provider. Set to empty string or null to remove.
          example: google
      additionalProperties: false
    Credential:
      type: object
      description: A stored credential for automatic re-authentication
      required:
      - id
      - name
      - domain
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the credential
          example: cred_abc123xyz
        name:
          type: string
          description: Unique name for the credential within the project
          example: my-netflix-login
        domain:
          type: string
          description: Target domain this credential is for
          example: netflix.com
        created_at:
          type: string
          format: date-time
          description: When the credential was created
          example: '2025-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the credential was last updated
          example: '2025-01-15T10:30:00Z'
        has_values:
          type: boolean
          description: Whether this credential has stored values (email, password, etc.)
          example: true
        has_totp_secret:
          type: boolean
          description: Whether this credential has a TOTP secret configured for automatic 2FA
          example: false
        sso_provider:
          type: string
          nullable: true
          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
        totp_code:
          type: string
          description: Current 6-digit TOTP code. Only included in create/update responses when totp_secret was just set.
          example: '847291'
        totp_code_expires_at:
          type: string
          format: date-time
          description: When the totp_code expires. Only included when totp_code is present.
          example: '2025-01-15T10:30:30Z'
      additionalProperties: false
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Application-specific error code (machine-readable)
          example: bad_request
        message:
          type: string
          description: Human-readable error description for debugging
          example: 'Missing required field: app_name'
        details:
          type: array
          description: Additional error details (for multiple errors)
          items:
            $ref: '#/components/schemas/ErrorDetail'
        inner_error:
          $ref: '#/components/schemas/ErrorDetail'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer