> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-docs-website-deploy-hook.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create auth connection > Creates an auth connection for a profile and domain combination. If the provided profile_name does not exist, it is created automatically. Returns 409 Conflict if an auth connection already exists for the given profile and domain. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/kernel/openapi.documented.yml post /auth/connections 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 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 Filesystem description: Read, write, and manage files on the browser instance. - name: Browser Processes description: Execute and manage processes on the browser instance. - name: Browser Replays description: Record and manage browser session video replays. - name: Browser Logs description: Stream logs from the browser instance. - name: Browser Telemetry description: Stream live telemetry events from a browser session. - name: Profiles description: Create, list, retrieve, and delete browser profiles. - name: Proxies description: Create and manage proxy configurations for routing browser traffic. - name: Extensions description: Create, list, retrieve, and delete browser extensions. - 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: Organization description: Read and manage organization-level limits. - name: Projects description: Create and manage projects for resource isolation within an organization. - name: API Keys description: Create and manage API keys for organization and project-scoped access. - name: Audit Logs description: Read audit log records for the authenticated organization. paths: /auth/connections: post: tags: - Managed Auth summary: Create auth connection description: >- Creates an auth connection for a profile and domain combination. If the provided profile_name does not exist, it is created automatically. Returns 409 Conflict if an auth connection already exists for the given profile and domain. operationId: postAuthConnections requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ManagedAuthCreateRequest' responses: '201': description: Auth connection created content: application/json: schema: $ref: '#/components/schemas/ManagedAuth' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: Auth connection already exists for this profile and domain content: application/json: schema: type: object required: - code - message - existing_id properties: code: type: string example: already_exists message: type: string example: Auth connection already exists for this profile and domain existing_id: type: string description: ID of the existing auth connection '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.create({ domain: 'netflix.com', profile_name: 'user-123', }); 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.create( domain="netflix.com", profile_name="user-123", ) 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.New(context.TODO(), kernel.AuthConnectionNewParams{\n\t\tManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{\n\t\t\tDomain: \"netflix.com\",\n\t\t\tProfileName: \"user-123\",\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: ManagedAuthCreateRequest: type: object description: Request to create an auth connection for a profile and domain 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 manage authentication for. If the profile does not exist, it is created automatically. example: user-123 login_url: type: string format: uri description: Optional login page URL to skip discovery example: https://netflix.com/login proxy: $ref: '#/components/schemas/ProxyRef' credential: $ref: '#/components/schemas/CredentialReference' allowed_domains: type: array items: type: string description: > Additional domains 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 health_check_interval: type: integer 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 health_checks: type: boolean default: true description: > Whether to enable periodic health checks. When false, the system will not automatically verify authentication status, and `auto_reauth` has no effect on the automatic flow (since re-auth is only triggered by a failed scheduled health check). Defaults to true. example: true auto_reauth: type: boolean default: true description: > Whether to permit automatic re-authentication when a scheduled health check detects an expired session. This is an opt-in flag only — it does not check whether re-auth is actually feasible. Even when true, re-auth only runs when the system has what it needs to perform it (for example, saved credentials for the required login fields), and only after a scheduled health check detects an expired session — so this flag has no effect when `health_checks` is false. When false, expired sessions are marked as `NEEDS_AUTH` instead of attempting re-auth. Defaults to true. example: true save_credentials: type: boolean default: true description: >- Whether to save credentials after every successful login. Defaults to true. One-time codes (TOTP, SMS, etc.) are not saved. example: true record_session: type: boolean default: false description: >- Whether to record browser sessions for this connection by default. Useful for debugging. Can be overridden per-login. Defaults to false. example: false 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 Kernel can automatically re-authenticate this connection when the session expires. Requires a prior successful login plus either a Kernel credential or an external credential reference. See `can_reauth_reason` for the specific outcome. example: true can_reauth_reason: type: string description: |- Machine-readable reason for the current value of `can_reauth`. Affirmative values (re-auth is possible): - `external_credential` — an external credential provider is attached - `cua_has_credential` — CUA flow with a stored credential - `has_credential` — Kernel credential is attached (optimistic; plan viability not checked) - `viable_plans_found` — at least one stored login plan can be replayed - `no_requirements_recorded` — no recorded credential requirements to fail against - `requirements_satisfiable` — recorded requirements can be met by the attached credential Negative values (a human must complete the login flow): - `no_prior_successful_login` — connection has never completed a successful login - `no_credential` — no Kernel or external credential attached - `no_viable_plans` — credential attached but no replayable login plan exists yet - `viable_plans_require_external_action` — stored plans need an external step (email link, push, etc.) - `requires_external_action` — recorded requirements include an external step - `requires_totp_without_secret` — flow needs a TOTP code but no TOTP secret is stored - `requires_sms_code` — flow needs an SMS code that cannot be received automatically - `requires_email_code` — flow needs an email code that cannot be received automatically enum: - external_credential - cua_has_credential - has_credential - viable_plans_found - no_requirements_recorded - requirements_satisfiable - no_prior_successful_login - no_credential - no_viable_plans - viable_plans_require_external_action - requires_external_action - requires_totp_without_secret - requires_sms_code - requires_email_code 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 health_checks: type: boolean description: > Whether periodic health checks are enabled for this connection. When false, the system will not automatically verify authentication status, and `auto_reauth` has no effect on the automatic flow (since re-auth is only triggered by a failed scheduled health check). Manually triggering a health check via the API still works regardless of this setting. example: true auto_reauth: type: boolean description: > Whether automatic re-authentication is permitted for this connection. This is an opt-in flag only — it does not check whether re-auth is actually feasible. Even when true, re-auth only runs when the system has what it needs to perform it (for example, saved credentials for the required login fields), and only after a scheduled health check detects an expired session — so this flag has no effect when `health_checks` is false. When false, expired sessions detected by a health check are marked as `NEEDS_AUTH` instead of attempting re-auth. example: true 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 ProxyRef: type: object description: > Proxy selection. Provide either id or name. The proxy must be in the same project as the resource referencing it. properties: id: type: string description: Proxy ID name: type: string description: Proxy name oneOf: - required: - id - required: - name 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 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' Forbidden: description: Forbidden – insufficient permissions or plan 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 ````