Appearance
Fresh 🌱
Update auth connection ​
Update an auth connection's configuration. Only the fields provided will be updated.
OpenAPI ​
yaml
openapi: 3.1.0
info:
title: Kernel 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: Browsers
description: Create and manage browser sessions.
- name: Browser Replays
description: Record and manage browser session video replays.
- name: Profiles
description: Create, list, retrieve, and delete browser profiles.
- name: Browser Filesystem
description: Read, write, and manage files on the browser instance.
- name: Browser Computer Controls
description: Control mouse, keyboard, and screen on the browser instance.
- name: Browser Playwright
description: Execute Playwright code against the browser instance.
- name: Browser Processes
description: Execute and manage processes on the browser instance.
- name: Browser Logs
description: Stream logs from the browser instance.
- name: Extensions
description: Create, list, retrieve, and delete browser extensions.
- name: Proxies
description: Create and manage proxy configurations for routing browser traffic.
- name: Browser Pools
description: Create and manage browser pools for acquiring and releasing browsers.
- name: Managed Auth
description: >-
Create and manage auth connections for automated credential capture and
login.
- name: Credentials
description: Create and manage credentials for authentication.
- name: Credential Providers
description: Configure external credential providers like 1Password.
- name: Apps
description: List applications and versions.
- name: Deployments
description: Create and manage app deployments and stream deployment events.
- name: Invocations
description: Invoke actions and stream or query invocation status and events.
- name: Projects
description: Create and manage projects for resource isolation within an organization.
paths:
/auth/connections/{id}:
patch:
tags:
- Managed Auth
summary: Update auth connection
description: >-
Update an auth connection's configuration. Only the fields provided will
be updated.
operationId: patchAuthConnectionsById
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Auth connection ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedAuthUpdateRequest'
responses:
'200':
description: Auth connection updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedAuth'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
security:
- bearerAuth: []
x-codeSamples:
- lang: JavaScript
source: |-
import Kernel from '@onkernel/sdk';
const client = new Kernel({
apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted
});
const managedAuth = await client.auth.connections.update('id');
console.log(managedAuth.id);
- lang: Python
source: |-
import os
from kernel import Kernel
client = Kernel(
api_key=os.environ.get("KERNEL_API_KEY"), # This is the default and can be omitted
)
managed_auth = client.auth.connections.update(
id="id",
)
print(managed_auth.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\tmanagedAuth, err := client.Auth.Connections.Update(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.AuthConnectionUpdateParams{\n\t\t\tManagedAuthUpdateRequest: kernel.ManagedAuthUpdateRequestParam{},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", managedAuth.ID)\n}\n"
components:
schemas:
ManagedAuthUpdateRequest:
type: object
description: Request to update an auth connection's configuration
properties:
login_url:
type: string
format: uri
description: Login page URL. Set to empty string to clear.
example: https://netflix.com/login
credential:
$ref: '#/components/schemas/CredentialReference'
allowed_domains:
type: array
items:
type: string
description: Additional domains valid for this auth flow (replaces existing list)
example:
- login.netflix.com
- auth.netflix.com
health_check_interval:
type: integer
minimum: 300
maximum: 86400
description: Interval in seconds between automatic health checks
example: 3600
save_credentials:
type: boolean
description: Whether to save credentials after every successful login
example: true
record_session:
type: boolean
description: Whether to record browser sessions for this connection by default
example: false
proxy:
$ref: '#/components/schemas/ProxyRef'
additionalProperties: false
ManagedAuth:
type: object
description: >-
Managed authentication that keeps a profile logged into a specific
domain. Flow fields (flow_status, flow_step, discovered_fields,
mfa_options) reflect the most recent login flow and are null when no
flow has been initiated.
required:
- id
- profile_name
- domain
- status
- save_credentials
- record_session
properties:
id:
type: string
description: Unique identifier for the auth connection
example: ma_abc123xyz
profile_name:
type: string
description: Name of the profile associated with this auth connection
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 most recent auth health check ran for this connection,
regardless of outcome. Updated on every health check and does not by
itself indicate that the profile is currently authenticated - use
`status` for that. May be newer than `flow_expires_at` when a flow
is still in progress because health checks continue to run in
parallel.
example: '2025-01-15T10:30:00Z'
last_auth_at:
type: string
format: date-time
deprecated: true
description: >-
Deprecated alias for `last_auth_check_at`. Despite the name, this is
the last health-check timestamp, not the last successful
authentication. Use `last_auth_check_at` instead.
example: '2025-01-15T10:30:00Z'
credential:
$ref: '#/components/schemas/CredentialReference'
can_reauth:
type: boolean
description: >-
Whether automatic re-authentication is possible (has credential,
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
proxy_id:
type: string
description: ID of the proxy associated with this connection, if any.
allowed_domains:
type: array
items:
type: string
description: >
Additional domains that are valid for this auth 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
login_url:
type: string
format: uri
description: Optional login page URL to skip discovery
example: https://example.com/login
post_login_url:
type: string
format: uri
description: URL where the browser landed after successful login
example: https://www.netflix.com/browse
flow_status:
type: string
enum:
- IN_PROGRESS
- SUCCESS
- FAILED
- EXPIRED
- CANCELED
nullable: true
description: Current flow status (null when no flow in progress)
example: IN_PROGRESS
flow_step:
type: string
enum:
- DISCOVERING
- AWAITING_INPUT
- AWAITING_EXTERNAL_ACTION
- SUBMITTING
- COMPLETED
nullable: true
description: Current step in the flow (null when no flow in progress)
example: AWAITING_INPUT
flow_type:
type: string
enum:
- LOGIN
- REAUTH
nullable: true
description: Type of the current flow (null when no flow in progress)
example: LOGIN
flow_expires_at:
type: string
format: date-time
nullable: true
description: >-
When the current flow expires (null when no flow in progress). A
flow past this timestamp is no longer valid and its `flow_status`
will be `EXPIRED`. Clients may start a new login to supersede a
stale `IN_PROGRESS` flow past this timestamp.
example: '2025-11-05T20:00:00Z'
discovered_fields:
type: array
nullable: true
description: >-
Fields awaiting input (present when flow_step=awaiting_input; may
also be present with awaiting_external_action as fallback actions)
items:
$ref: '#/components/schemas/DiscoveredField'
mfa_options:
type: array
nullable: true
description: >-
MFA method options (present when flow_step=awaiting_input; may also
be present with awaiting_external_action as fallback actions)
items:
$ref: '#/components/schemas/MFAOption'
sign_in_options:
type: array
nullable: true
description: >-
Non-MFA choices presented during the auth flow, such as account
selection or org pickers (present when flow_step=awaiting_input; may
also be present with awaiting_external_action as fallback actions).
items:
$ref: '#/components/schemas/SignInOption'
pending_sso_buttons:
type: array
nullable: true
description: >-
SSO buttons available (present when flow_step=awaiting_input; may
also be present with awaiting_external_action as fallback actions)
items:
$ref: '#/components/schemas/SSOButton'
external_action_message:
type: string
nullable: true
description: >-
Instructions for external action (present when
flow_step=awaiting_external_action)
example: Tap 'Yes' on the Google prompt on your phone
website_error:
type: string
nullable: true
description: >-
Visible error message from the website (e.g., 'Incorrect password').
Present when the website displays an error during login.
sso_provider:
type: string
nullable: true
description: SSO provider being used (e.g., google, github, microsoft)
example: google
error_message:
type: string
nullable: true
description: Error message (present when flow_status=failed)
example: Invalid password
error_code:
type: string
nullable: true
description: Machine-readable error code (present when flow_status=failed)
hosted_url:
type: string
format: uri
nullable: true
description: >-
URL to redirect user to for hosted login (present when flow in
progress)
example: https://auth.kernel.com/login/abc123xyz
live_view_url:
type: string
format: uri
nullable: true
description: Browser live view URL for debugging (present when flow in progress)
example: https://live.kernel.com/abc123xyz
browser_session_id:
type: string
nullable: true
description: >
ID of the underlying browser session driving the current flow
(present when flow in progress).
Use this to inspect or terminate the browser session via the
`/browsers` API.
example: bs_abc123xyz
health_check_interval:
type: integer
nullable: true
minimum: 300
maximum: 86400
description: >
Interval in seconds between automatic health checks. When set, the
system periodically
verifies the authentication status and triggers re-authentication if
needed.
Maximum is 86400 (24 hours). Default is 3600 (1 hour). The minimum
depends on your plan:
Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist:
3600 (1 hour).
example: 3600
save_credentials:
type: boolean
description: >-
Whether credentials are saved after every successful login. One-time
codes (TOTP, SMS, etc.) are not saved.
example: true
record_session:
type: boolean
description: >-
Whether to record browser session replays for this connection by
default. Useful for debugging login flows. Can be overridden
per-login.
example: false
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
ProxyRef:
type: object
description: >
Proxy selection. Provide either id or name. The proxy must belong to the
caller's org.
properties:
id:
type: string
description: Proxy ID
name:
type: string
description: Proxy name
oneOf:
- required:
- id
- required:
- name
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
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
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
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
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'
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
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
responses:
BadRequest:
description: Bad Request - invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized - missing or invalid authorization token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer