Kernel Auth Connections API
The Auth Connections API from Kernel — 6 operation(s) for auth connections.
OpenAPI Specification
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