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.

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

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)

package main

import (
	"context"
	"fmt"

	"github.com/kernel/kernel-go-sdk"
	"github.com/kernel/kernel-go-sdk/option"
)

func main() {
	client := kernel.NewClient(
		option.WithAPIKey("My API Key"),
	)
	managedAuth, err := client.Auth.Connections.New(context.TODO(), kernel.AuthConnectionNewParams{
		ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
			Domain:      "netflix.com",
			ProfileName: "user-123",
		},
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", managedAuth.ID)
}

curl --request POST \
  --url https://api.onkernel.com/auth/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": "netflix.com",
  "profile_name": "user-123",
  "login_url": "https://netflix.com/login",
  "proxy": {
    "id": "<string>",
    "name": "<string>"
  },
  "credential": {
    "name": "my-netflix-creds",
    "provider": "my-1p",
    "path": "Personal/Netflix",
    "auto": true
  },
  "allowed_domains": [
    "login.netflix.com",
    "auth.netflix.com"
  ],
  "health_check_interval": 3600,
  "save_credentials": true
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onkernel.com/auth/connections",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'domain' => 'netflix.com',
    'profile_name' => 'user-123',
    'login_url' => 'https://netflix.com/login',
    'proxy' => [
        'id' => '<string>',
        'name' => '<string>'
    ],
    'credential' => [
        'name' => 'my-netflix-creds',
        'provider' => 'my-1p',
        'path' => 'Personal/Netflix',
        'auto' => true
    ],
    'allowed_domains' => [
        'login.netflix.com',
        'auth.netflix.com'
    ],
    'health_check_interval' => 3600,
    'save_credentials' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.onkernel.com/auth/connections")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"domain\": \"netflix.com\",\n  \"profile_name\": \"user-123\",\n  \"login_url\": \"https://netflix.com/login\",\n  \"proxy\": {\n    \"id\": \"<string>\",\n    \"name\": \"<string>\"\n  },\n  \"credential\": {\n    \"name\": \"my-netflix-creds\",\n    \"provider\": \"my-1p\",\n    \"path\": \"Personal/Netflix\",\n    \"auto\": true\n  },\n  \"allowed_domains\": [\n    \"login.netflix.com\",\n    \"auth.netflix.com\"\n  ],\n  \"health_check_interval\": 3600,\n  \"save_credentials\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onkernel.com/auth/connections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"domain\": \"netflix.com\",\n  \"profile_name\": \"user-123\",\n  \"login_url\": \"https://netflix.com/login\",\n  \"proxy\": {\n    \"id\": \"<string>\",\n    \"name\": \"<string>\"\n  },\n  \"credential\": {\n    \"name\": \"my-netflix-creds\",\n    \"provider\": \"my-1p\",\n    \"path\": \"Personal/Netflix\",\n    \"auto\": true\n  },\n  \"allowed_domains\": [\n    \"login.netflix.com\",\n    \"auth.netflix.com\"\n  ],\n  \"health_check_interval\": 3600,\n  \"save_credentials\": true\n}"

response = http.request(request)
puts response.read_body

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"
  ],
  "login_url": "https://example.com/login",
  "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",
      "hint": "Enter the phone ending in (***) ***-**92"
    }
  ],
  "mfa_options": [
    {
      "type": "sms",
      "label": "Text me a code",
      "target": "***-***-5678",
      "description": "We'll send a 6-digit code to your phone"
    }
  ],
  "sign_in_options": [
    {
      "id": "work-account",
      "label": "Work Account ([e-mail])",
      "description": "[e-mail]"
    }
  ],
  "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",
  "error_code": "<string>",
  "hosted_url": "https://auth.kernel.com/login/abc123xyz",
  "live_view_url": "https://live.kernel.com/abc123xyz",
  "health_check_interval": 3600
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "already_exists",
  "message": "Auth connection already exists for this profile and domain",
  "existing_id": "<string>"
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

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. If the profile does not exist, it is created automatically.

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

login_url · string<uri>

Optional login page URL to skip discovery

Example:

"https://example.com/login"

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

sign_in_options · object[] | null

Non-MFA choices presented during the auth flow, such as account selection or org pickers (present when flow_step=awaiting_input).

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"

error_code · string | null

Machine-readable error code (present when flow_status=failed)

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