openapi: 3.1.0
info:
  title: Kernel API Keys Auth Connections 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: Auth Connections
paths:
  /agents/auth:
    post:
      x-hidden: true
      deprecated: true
      operationId: postAgentsAuth
      tags:
      - Auth Connections
      summary: Create or find an auth agent
      description: '**Deprecated: Use POST /auth/connections instead.** Creates a new auth agent for the specified domain and profile combination, or returns an existing one if it already exists. This is idempotent - calling with the same domain and profile will return the same agent. Does NOT start an invocation - use POST /agents/auth/invocations to start an auth flow.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthAgentCreateRequest'
      responses:
        '200':
          description: Auth agent created or found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthAgent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      x-hidden: true
      deprecated: true
      operationId: getAgentsAuth
      tags:
      - Auth Connections
      summary: List auth agents
      description: '**Deprecated: Use GET /auth/connections instead.** List auth agents with optional filters for profile_name and domain.'
      security:
      - bearerAuth: []
      parameters:
      - name: profile_name
        in: query
        required: false
        schema:
          type: string
        description: Filter by profile name
      - 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 auth agents
          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/AuthAgent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/auth/invocations:
    post:
      x-hidden: true
      deprecated: true
      operationId: postAgentsAuthInvocations
      tags:
      - Auth Connections
      summary: Create an auth invocation
      description: '**Deprecated: Use POST /auth/connections/{id}/login instead.** Creates a new authentication invocation for the specified auth agent. This starts the auth flow and returns a hosted URL for the user to complete authentication.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthAgentInvocationCreateRequest'
      responses:
        '200':
          description: Invocation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthAgentInvocationCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/auth/{id}:
    get:
      x-hidden: true
      deprecated: true
      operationId: getAgentsAuthById
      tags:
      - Auth Connections
      summary: Get auth agent by ID
      description: '**Deprecated: Use GET /auth/connections/{id} instead.** Retrieve an auth agent by its ID. Returns the current authentication status of the managed profile.'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Auth agent ID
      responses:
        '200':
          description: Auth agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthAgent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      x-hidden: true
      deprecated: true
      operationId: deleteAgentsAuthById
      tags:
      - Auth Connections
      summary: Delete auth agent
      description: '**Deprecated: Use DELETE /auth/connections/{id} instead.**

        Deletes an auth agent and terminates its workflow. This will:

        - Soft delete the auth agent record

        - Gracefully terminate the agent''s Temporal workflow

        - Cancel any in-progress invocations

        '
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Auth agent ID
      responses:
        '204':
          description: Auth agent deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/auth/invocations/{invocation_id}:
    get:
      x-hidden: true
      deprecated: true
      operationId: getAgentsAuthInvocationsInvocationId
      tags:
      - Auth Connections
      summary: Get invocation details
      description: '**Deprecated: Use GET /auth/connections/{id} instead.** Returns invocation details including status, app_name, and domain. Supports both API key and JWT (from exchange endpoint) authentication.'
      security:
      - bearerAuth: []
      parameters:
      - name: invocation_id
        in: path
        required: true
        schema:
          type: string
        description: Invocation ID
      responses:
        '200':
          description: Invocation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAuthInvocationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/auth/invocations/{invocation_id}/exchange:
    post:
      x-hidden: true
      deprecated: true
      x-cli-skip: true
      operationId: postAgentsAuthInvocationsExchange
      tags:
      - Auth Connections
      summary: Exchange handoff code for JWT
      description: '**Deprecated: Use POST /auth/connections/{id}/exchange instead.** Validates the handoff code and returns a JWT token for subsequent requests. No authentication required (the handoff code serves as the credential).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagedAuthExchangeRequest'
      parameters:
      - name: invocation_id
        in: path
        required: true
        schema:
          type: string
        description: Invocation ID from start endpoint
      responses:
        '200':
          description: Exchange successful, JWT returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAuthExchangeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/auth/invocations/{invocation_id}/submit:
    post:
      x-hidden: true
      deprecated: true
      operationId: postAgentsAuthInvocationsSubmit
      tags:
      - Auth Connections
      summary: Submit field values
      description: '**Deprecated: Use POST /auth/connections/{id}/submit instead.** Submits field values for the discovered login form. Returns immediately after submission is accepted. Poll the invocation endpoint to track progress and get results.'
      security:
      - bearerAuth: []
      parameters:
      - name: invocation_id
        in: path
        required: true
        schema:
          type: string
        description: Invocation ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentAuthSubmitRequest'
      responses:
        '202':
          description: Submission accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAuthSubmitResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    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
    SSOButton:
      type: object
      description: An SSO button for signing in with an external identity provider
      properties:
        selector:
          type: string
          description: XPath selector for the button
          example: xpath=//button[contains(text(), 'Continue with Google')]
        provider:
          type: string
          description: Identity provider name
          example: google
        label:
          type: string
          description: Visible button text
          example: Continue with Google
      required:
      - selector
      - provider
      - label
      additionalProperties: false
    ManagedAuthExchangeRequest:
      type: object
      description: Request to exchange handoff code for JWT
      required:
      - code
      properties:
        code:
          type: string
          description: Handoff code from start endpoint
          example: abc123xyz
      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'
    AgentAuthSubmitRequest:
      type: object
      description: Request to submit an auth form. Provide exactly one of field_values, sso_button, or selected_mfa_type.
      oneOf:
      - required:
        - field_values
        properties:
          field_values:
            type: object
            description: Values for the discovered login fields
            additionalProperties:
              type: string
            example:
              email: user@example.com
              password: '********'
      - required:
        - sso_button
        properties:
          sso_button:
            type: string
            description: Selector of SSO button to click
            example: xpath=//button[contains(text(), 'Continue with Google')]
      - required:
        - selected_mfa_type
        properties:
          selected_mfa_type:
            allOf:
            - $ref: '#/components/schemas/MFAType'
            - description: The MFA method type to select (when mfa_options were returned)
      additionalProperties: false
    AgentAuthInvocationResponse:
      type: object
      description: Response from get invocation endpoint
      required:
      - app_name
      - domain
      - status
      - step
      - type
      - expires_at
      properties:
        app_name:
          type: string
          description: App name (org name at time of invocation creation)
          example: Acme Corp
        domain:
          type: string
          description: Domain for authentication
          example: doordash.com
        status:
          type: string
          enum:
          - IN_PROGRESS
          - SUCCESS
          - EXPIRED
          - CANCELED
          - FAILED
          description: Invocation status
          example: IN_PROGRESS
        step:
          type: string
          enum:
          - initialized
          - discovering
          - awaiting_input
          - awaiting_external_action
          - submitting
          - completed
          - expired
          description: Current step in the invocation workflow
          example: awaiting_input
        type:
          type: string
          enum:
          - login
          - reauth
          description: 'The session type:

            - login: User-initiated authentication

            - reauth: System-triggered re-authentication (via health check)

            '
          example: login
        expires_at:
          type: string
          format: date-time
          description: When the handoff code expires
          example: '2025-11-05T20:00:00Z'
        pending_fields:
          type: array
          nullable: true
          description: Fields currently awaiting input (present when step=awaiting_input)
          items:
            $ref: '#/components/schemas/DiscoveredField'
        mfa_options:
          type: array
          nullable: true
          description: MFA method options to choose from (present when step=awaiting_input and MFA selection is required)
          items:
            $ref: '#/components/schemas/MFAOption'
        sign_in_options:
          type: array
          nullable: true
          description: Non-MFA choices to select from (present when step=awaiting_input and account/org selection is required)
          items:
            $ref: '#/components/schemas/SignInOption'
        submitted_fields:
          type: array
          nullable: true
          description: Names of fields that have been submitted (present when step=submitting or later)
          items:
            type: string
          example:
          - identifier
          - password
        error_message:
          type: string
          nullable: true
          description: Error message explaining why the invocation failed (present when status=FAILED)
          example: Invalid password
        live_view_url:
          type: string
          nullable: true
          description: Browser live view URL for debugging the invocation
          example: https://live.kernel.com/abc123xyz
        pending_sso_buttons:
          type: array
          nullable: true
          description: SSO buttons available on the page (present when step=awaiting_input)
          items:
            $ref: '#/components/schemas/SSOButton'
        external_action_message:
          type: string
          nullable: true
          description: Instructions for user when external action is required (present when step=awaiting_external_action)
          example: Tap 'Yes' on the Google prompt on your phone
        sso_provider:
          type: string
          nullable: true
          description: SSO provider being used for authentication (e.g., google, github, microsoft)
          example: google
      additionalProperties: false
    AuthAgentInvocationCreateResponse:
      type: object
      description: Response from creating an invocation. Always returns an invocation_id.
      required:
      - invocation_id
      - type
      - handoff_code
      - hosted_url
      - expires_at
      properties:
        invocation_id:
          type: string
          description: Unique identifier for the invocation.
          example: abc123xyz
        type:
          type: string
          enum:
          - login
          - reauth
          description: 'The session type:

            - login: User-initiated authentication

            - reauth: System-triggered re-authentication (via health check)

            '
          example: login
        handoff_code:
          type: string
          description: One-time code for handoff.
          example: aBcD123EfGh456IjKl789MnOp012QrStUvWxYzAbCdEf
        hosted_url:
          type: string
          format: uri
          description: URL to redirect user to.
          example: https://agent-auth.kernel.com/agents/auth/invocations/abc123xyz?code=abc123xyz
        expires_at:
          type: string
          format: date-time
          description: When the handoff code expires.
          example: '2025-11-05T20:00:00Z'
      additionalProperties: false
    AuthAgentInvocationCreateRequest:
      type: object
      description: Request to create an invocation for an existing auth agent
      required:
      - auth_agent_id
      properties:
        auth_agent_id:
          type: string
          description: ID of the auth agent to create an invocation for
          example: abc123xyz
        save_credential_as:
          type: string
          description: If provided, saves the submitted credentials under this name upon successful login. The credential will be linked to the auth agent for automatic re-authentication.
          example: my-netflix-login
      additionalProperties: false
    AuthAgent:
      type: object
      description: An auth agent that manages authentication for a specific domain and profile combination
      required:
      - id
      - profile_name
      - domain
      - status
      properties:
        id:
          type: string
          description: Unique identifier for the auth agent
          example: abc123xyz
        profile_name:
          type: string
          description: Name of the profile associated with this auth agent
          example: my-netflix-profile
        domain:
          type: string
          description: Target domain for authentication
          example: netflix.com
        status:
          type: string
          enum:
          - AUTHENTICATED
          - NEEDS_AUTH
          description: Current authentication status of the managed profile
          example: AUTHENTICATED
        last_auth_check_at:
          type: string
          format: date-time
          description: When the last authentication check was performed
          example: '2025-01-15T10:30:00Z'
        credential_id:
          type: string
          description: ID of the linked Kernel credential for automatic re-authentication (deprecated, use credential)
          example: cred_abc123xyz
        credential:
          $ref: '#/components/schemas/CredentialReference'
        has_selectors:
          type: boolean
          description: Whether this auth agent has stored selectors for deterministic re-authentication
          example: true
        can_reauth:
          type: boolean
          description: Whether automatic re-authentication is possible (has credential_id, selectors, and login_url)
          example: true
        can_reauth_reason:
          type: string
          description: Reason why automatic re-authentication is or is not possible
          example: has_credential
        allowed_domains:
          type: array
          items:
            type: string
          description: 'Additional domains that are valid for this auth agent''s authentication flow (besides the primary domain). Useful when login pages redirect to different domains.


            The following SSO/OAuth provider domains are automatically allowed by default and do not need to be specified:

            - Google: accounts.google.com

            - Microsoft/Azure AD: login.microsoftonline.com, login.live.com

            - Okta: *.okta.com, *.oktapreview.com

            - Auth0: *.auth0.com, *.us.auth0.com, *.eu.auth0.com, *.au.auth0.com

            - Apple: appleid.apple.com

            - GitHub: github.com

            - Facebook/Meta: www.facebook.com

            - LinkedIn: www.linkedin.com

            - Amazon Cognito: *.amazoncognito.com

            - OneLogin: *.onelogin.com

            - Ping Identity: *.pingone.com, *.pingidentity.com

            '
          example:
          - login.netflix.com
          - auth.netflix.com
        post_login_url:
          type: string
          format: uri
          description: URL where the browser landed after successful login. Query parameters and fragments are stripped for privacy.
          example: https://www.netflix.com/browse
      additionalProperties: false
    AuthAgentCreateRequest:
      type: object
      description: Request to create or find an auth agent
      required:
      - domain
      - profile_name
      properties:
        domain:
          type: string
          description: Domain for authentication
          example: netflix.com
        profile_name:
          type: string
          description: Name of the profile to use for this auth agent
          example: user-123
        login_url:
          type: string
          format: uri
          description: Optional login page URL. If provided, will be stored on the agent and used to skip discovery in future invocations.
          example: https://netflix.com/login
        proxy:
          type: object
          description: Optional proxy configuration
          properties:
            proxy_id:
              type: string
              description: ID of the proxy to use
          additionalProperties: false
        credential_name:
          type: string
          description: Optional name of an existing credential to use for this auth agent. If provided, the credential will be linked to the agent and its values will be used to auto-fill the login form on invocation.
          example: my-netflix-login
        allowed_domains:
          type: array
          items:
            type: string
          description: 'Additional domains that are valid for this auth agent''s authentication flow (besides the primary domain). Useful when login pages redirect to different domains.


            The following SSO/OAuth provider domains are automatically allowed by default and do not need to be specified:

            - Google: accounts.google.com

            - Microsoft/Azure AD: login.microsoftonline.com, login.live.com

            - Okta: *.okta.com, *.oktapreview.com

            - Auth0: *.auth0.com, *.us.auth0.com, *.eu.auth0.com, *.au.auth0.com

            - Apple: appleid.apple.com

            - GitHub: github.com

            - Facebook/Meta: www.facebook.com

            - LinkedIn: www.linkedin.com

            - Amazon Cognito: *.amazoncognito.com

            - OneLogin: *.onelogin.com

            - Ping Identity: *.pingone.com, *.pingidentity.com

            '
          example:
          - login.netflix.com
          - auth.netflix.com
      additionalProperties: false
    DiscoveredField:
      type: object
      description: A discovered form field
      properties:
        name:
          type: string
          description: Field name
          example: email
        type:
          type: string
          enum:
          - text
          - email
          - password
          - tel
          - number
          - url
          - code
          - totp
          description: Field type
          example: email
        label:
          type: string
          description: Field label
          example: Email address
        placeholder:
          type: string
          description: Field placeholder
          example: you@example.com
        required:
          type: boolean
          description: Whether field is required
          default: true
          example: true
        selector:
          type: string
          description: CSS selector for the field
          example: input#email
        linked_mfa_type:
          $ref: '#/components/schemas/MFAType'
          nullable: true
          description: If this field is associated with an MFA option, the type of that option (e.g., password field linked to "Enter password" option)
        hint:
          type: string
          description: Contextual help text near the field that tells the user what to enter (e.g., "Enter the phone ending in (***) ***-**92")
          example: Enter the phone ending in (***) ***-**92
      required:
      - name
      - type
      - label
      - selector
      additionalProperties: false
    CredentialReference:
      type: object
      description: 'Reference to credentials for the auth connection. Use one of:

        - { name } for Kernel credentials

        - { provider, path } for external provider item

        - { provider, auto: true } for external provider domain lookup

        '
      properties:
        name:
          type: string
          description: Kernel credential name
          example: my-netflix-creds
        provider:
          type: string
          description: External provider name (e.g., "my-1p")
          example: my-1p
        path:
          type: string
          description: Provider-specific path (e.g., "VaultName/ItemName" for 1Password)
          example: Personal/Netflix
        auto:
          type: boolean
          description: If true, lookup by domain from the specified provider
          example: true
      additionalProperties: false
    MFAType:
      type: string
      enum:
      - sms
      - call
      - email
      - totp
      - push
      - password
      - switch
      description: The MFA delivery method type. Includes 'password' for auth method selection pages and 'switch' for generic method-switcher links like "Use another method" that do not name a specific method.
      example: sms
    SignInOption:
      type: object
      description: A non-MFA choice presented during the auth flow (e.g. account selection, org picker)
      properties:
        id:
          type: string
          description: Unique identifier for this option (used to submit selection back)
          example: work-account
        label:
          type: string
          description: Display text for the option
          example: Work Account (user@company.com)
        description:
          type: string
          nullable: true
          description: Additional context such as email address or org name
          example: user@company.com
      required:
      - id
      - label
      additionalProperties: false
    AgentAuthSubmitResponse:
      type: object
      description: Response from submit endpoint - returns immediately after submission is accepted
      required:
      - accepted
      properties:
        accepted:
          type: boolean
          description: Whether the submission was accepted for processing
      additionalProperties: false
    ManagedAuthExchangeResponse:
      type: object
      description: Response from exchange endpoint
      required:
      - invocation_id
      - jwt
      properties:
        invocation_id:
          type: string
          description: Invocation ID
          example: abc123xyz
        jwt:
          type: string
          description: JWT token with invocation_id claim (30 minute TTL)
          example: eyJ0eXAi...
      additionalProperties: false
    MFAOption:
      type: object
      description: An MFA method option for verification
      properties:
        type:
          $ref: '#/components/schemas/MFAType'
        label:
          type: string
          description: The visible option text
          example: Text me a code
        target:
          type: string
          nullable: true
          description: The masked destination (phone/email) if shown
          example: '***-***-5678'
        description:
          type: string
          nullable: true
          description: Additional instructions from the site
          example: We'll send a 6-digit code to your phone
      required:
      - type
      - label
      additionalProperties: false
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden – insufficient permissions or plan
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Gone:
      description: Resource expired or no longer available
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized – missing or invalid authorization token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request – invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer