Create auth connection

Creates an auth connection for a profile and domain combination. Returns 409 Conflict if an auth connection already exists for the given profile and domain.

POST /auth/connections

JavaScript

JavaScript

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);

201

{
  "id": "ma_abc123xyz",
  "profile_name": "my-netflix-profile",
  "domain": "netflix.com",
  "status": "AUTHENTICATED",
  "save_credentials": true,
  "last_auth_at": "2025-01-15T10:30:00Z",
  "credential": {
    "name": "my-netflix-creds",
    "provider": "my-1p",
    "path": "Personal/Netflix",
    "auto": true
  },
  "can_reauth": true,
  "can_reauth_reason": "has_credential",
  "proxy_id": "<string>",
  "allowed_domains": [
    "login.netflix.com",
    "auth.netflix.com"
  ],
  "post_login_url": "https://www.netflix.com/browse",
  "flow_status": "IN_PROGRESS",
  "flow_step": "AWAITING_INPUT",
  "flow_type": "LOGIN",
  "flow_expires_at": "2025-11-05T20:00:00Z",
  "discovered_fields": [
    {
      "name": "email",
      "type": "email",
      "label": "Email address",
      "selector": "input#email",
      "placeholder": "[e-mail]",
      "required": true,
      "linked_mfa_type": "sms"
    }
  ],
  "mfa_options": [
    {
      "type": "sms",
      "label": "Text me a code",
      "target": "***-***-5678",
      "description": "We'll send a 6-digit code to your phone"
    }
  ],
  "pending_sso_buttons": [
    {
      "selector": "xpath=//button[contains(text(), 'Continue with Google')]",
      "provider": "google",
      "label": "Continue with Google"
    }
  ],
  "external_action_message": "Tap 'Yes' on the Google prompt on your phone",
  "website_error": "<string>",
  "sso_provider": "google",
  "error_message": "Invalid password",
  "hosted_url": "https://auth.kernel.com/login/abc123xyz",
  "live_view_url": "https://live.kernel.com/abc123xyz",
  "health_check_interval": 3600
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request to create an auth connection for a profile and domain

domain · string · required

Domain for authentication

Example:

"netflix.com"

profile_name · string · required

Name of the profile to manage authentication for

Example:

"user-123"

login_url · string<uri>

Optional login page URL to skip discovery

Example:

"https://netflix.com/login"

proxy · object

Proxy selection. Provide either id or name. The proxy must belong to the caller's org.

Option 1

Option 2

Show child attributes

credential · object

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

Show child attributes

allowed_domains · string[]

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 · integer

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).

Required range: 300 <= x <= 86400

Example:

3600

save_credentials · boolean · default: true

Whether to save credentials after every successful login. Defaults to true. One-time codes (TOTP, SMS, etc.) are not saved.

Example:

true

Response

201

application/json

Auth connection created

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.

id · string · required

Unique identifier for the auth connection

Example:

"ma_abc123xyz"

profile_name · string · required

Name of the profile associated with this auth connection

Example:

"my-netflix-profile"

domain · string · required

Target domain for authentication

Example:

"netflix.com"

status · enum<string> · required

Current authentication status of the managed profile

Available options: AUTHENTICATED, NEEDS_AUTH

Example:

"AUTHENTICATED"

save_credentials · boolean · required

Whether credentials are saved after every successful login. One-time codes (TOTP, SMS, etc.) are not saved.

Example:

true

last_auth_at · string<date-time>

When the profile was last successfully authenticated

Example:

"2025-01-15T10:30:00Z"

credential · object

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

Show child attributes

can_reauth · boolean

Whether automatic re-authentication is possible (has credential, selectors, and login_url)

Example:

true

can_reauth_reason · string

Reason why automatic re-authentication is or is not possible

Example:

"has_credential"

proxy_id · string

ID of the proxy associated with this connection, if any.

allowed_domains · string[]

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"]

post_login_url · string<uri>

URL where the browser landed after successful login

Example:

"https://www.netflix.com/browse"

flow_status · enum<string> | null

Current flow status (null when no flow in progress)

Available options: IN_PROGRESS, SUCCESS, FAILED, EXPIRED, CANCELED

Example:

"IN_PROGRESS"

flow_step · enum<string> | null

Current step in the flow (null when no flow in progress)

Available options: DISCOVERING, AWAITING_INPUT, AWAITING_EXTERNAL_ACTION, SUBMITTING, COMPLETED

Example:

"AWAITING_INPUT"

flow_type · enum<string> | null

Type of the current flow (null when no flow in progress)

Available options: LOGIN, REAUTH

Example:

"LOGIN"

flow_expires_at · string<date-time> | null

When the current flow expires (null when no flow in progress)

Example:

"2025-11-05T20:00:00Z"

discovered_fields · object[] | null

Fields awaiting input (present when flow_step=awaiting_input)

Show child attributes

mfa_options · object[] | null

MFA method options (present when flow_step=awaiting_input and MFA selection required)

Show child attributes

pending_sso_buttons · object[] | null

SSO buttons available (present when flow_step=awaiting_input)

Show child attributes

external_action_message · string | null

Instructions for external action (present when flow_step=awaiting_external_action)

Example:

"Tap 'Yes' on the Google prompt on your phone"

website_error · string | null

Visible error message from the website (e.g., 'Incorrect password'). Present when the website displays an error during login.

sso_provider · string | null

SSO provider being used (e.g., google, github, microsoft)

Example:

"google"

error_message · string | null

Error message (present when flow_status=failed)

Example:

"Invalid password"

hosted_url · string<uri> | null

URL to redirect user to for hosted login (present when flow in progress)

Example:

"https://auth.kernel.com/login/abc123xyz"

live_view_url · string<uri> | null

Browser live view URL for debugging (present when flow in progress)

Example:

"https://live.kernel.com/abc123xyz"

health_check_interval · integer | null

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).

Required range: 300 <= x <= 86400

Example:

3600