KEkernel
Managed Auth

List auth connections

Changed on

List auth connections with optional filters for profile_name and domain.

get/auth/connections

Request

  • Base URL
    https://api.onkernel.com
  • URL
    https://api.onkernel.com/auth/connections
  • Auth
    HTTP bearer

Query parameters

profile_namestring

Filter by profile name

domainstring

Filter by domain

limitinteger

Maximum number of results to return

offsetinteger

Number of results to skip

querystring

Search auth connections by ID, domain, or profile name.

Response

List of auth connections

allowed_domainsstring[]

Additional hostname roots valid for this auth flow, besides the primary domain. Each value allows credential entry on that exact hostname and its subdomains. Leading www. and *. labels are normalized away. When omitted or empty, credential entry is unrestricted.

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
auto_reauthboolean

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.

browser_session_idstring nullable

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.

can_reauthboolean

Whether this connection's stored requirements are eligible for unattended re-authentication. A true value can represent either fully satisfiable requirements or a best-effort attempt. It does not account for whether automatic re-authentication is enabled or parent workflow state such as an active flow or circuit-breaker cooldown, so it does not guarantee an attempt on the next health check. See can_reauth_reason for the specific outcome.

can_reauth_reason'external_credential' | 'cua_has_credential' | 'has_credential' | 'viable_plans_found' | 'no_requirements_recorded' | 'totp_reauth_allowed' | 'optimistic_totp_attempt' | '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' | 'requires_customer_input'

Machine-readable reason for the current value of can_reauth. Affirmative values (requirements are eligible for unattended re-authentication):

  • 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
  • totp_reauth_allowed — TOTP is the only recorded requirement and a stored secret can generate the code
  • optimistic_totp_attempt — TOTP was previously required but no reusable secret is stored; the connection remains eligible for a circuit-breaker-bounded attempt because the site may not challenge returning sessions
  • requirements_satisfiable — recorded requirements contain no recognized blocker

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
  • requires_customer_input — flow needs another field or choice that is unavailable during unattended re-authentication
domainstring required

Target domain for authentication

error_codestring nullable

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

error_messagestring nullable

Error message (present when flow_status=failed)

external_action_messagestring nullable

Instructions for external action (present when flow_step=awaiting_external_action)

flow_expires_atstring date-time nullable

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.

flow_status'IN_PROGRESS' | 'SUCCESS' | 'FAILED' | 'EXPIRED' | 'CANCELED' nullable

Current flow status (null when no flow in progress)

flow_step'DISCOVERING' | 'AWAITING_INPUT' | 'AWAITING_EXTERNAL_ACTION' | 'AWAITING_HUMAN_INTERVENTION' | 'SUBMITTING' | 'COMPLETED' nullable

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

flow_type'LOGIN' | 'REAUTH' nullable

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

health_check_intervalinteger nullable

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) or your plan minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 hours).

health_check_unavailable_reason'no_auth_check_url'

Why health checks cannot verify this connection. Present when health checks are enabled but no auth check URL is available; a recent last_auth_check_at is not evidence of a valid session.

health_checksboolean

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.

hitlboolean required

Whether a login blocked by a CAPTCHA the browser cannot solve pauses at AWAITING_HUMAN_INTERVENTION so a person can complete it in the live view.

hosted_urlstring uri nullable

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

idstring required

Unique identifier for the auth connection

interaction_idstring nullable

Opaque identifier for the current canonical interaction. Required when submitting fields or choices and changes for each new actionable pause.

last_auth_atstring date-time

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.

last_auth_check_atstring date-time

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.

live_view_urlstring uri nullable

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

login_urlstring uri

Optional login page URL to skip discovery

post_login_urlstring uri

URL where the browser landed after successful login

profile_namestring required

Name of the profile associated with this auth connection

proxy_idstring

Deprecated. Read browser.proxy instead. Retained during migration for existing clients.

record_sessionboolean required

Whether to record browser session replays for this connection by default. Useful for debugging login flows. Can be overridden per-login.

save_credentialsboolean required

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

sso_providerstring nullable

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

status'AUTHENTICATED' | 'NEEDS_AUTH' required

Last known authentication status of the managed profile. An inconclusive health check preserves this status and does not verify the current session.

website_errorstring nullable

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

Example response

[
  {
    "allowed_domains": [
      "login.netflix.com",
      "auth.netflix.com"
    ],
    "auto_reauth": true,
    "browser_session_id": "bs_abc123xyz",
    "can_reauth": true,
    "can_reauth_reason": "has_credential",
    "choices": [
      {
        "id": "google",
        "label": "Google",
        "mfa_type": "sms",
        "observed_selector": "button:has-text(\"Google\")",
        "type": "sso_provider"
      }
    ],
    "credential": {
      "auto": true,
      "name": "my-netflix-creds",
      "path": "Personal/Netflix",
      "provider": "my-1p"
    },
    "discovered_fields": [
      {
        "hint": "Enter the phone ending in (***) ***-**92",
        "label": "Email address",
        "linked_mfa_type": "sms",
        "name": "email",
        "placeholder": "you@example.com",
        "required": true,
        "selector": "input#email",
        "type": "email"
      }
    ],
    "domain": "netflix.com",
    "error_message": "Invalid password",
    "external_action_message": "Tap 'Yes' on the Google prompt on your phone",
    "fields": [
      {
        "id": "field_email",
        "input_mode": "email",
        "label": "Email address",
        "observed_selector": "input[name=\"identifier\"]",
        "reason": "missing",
        "ref": "email",
        "type": "identifier"
      }
    ],
    "flow_expires_at": "2025-11-05T20:00:00Z",
    "flow_status": "IN_PROGRESS",
    "flow_step": "AWAITING_INPUT",
    "flow_type": "LOGIN",
    "health_check_interval": 3600,
    "health_checks": true,
    "hosted_url": "https://auth.kernel.com/login/abc123xyz",
    "id": "ma_abc123xyz",
    "interaction_id": "mai_abc123xyz",
    "last_auth_at": "2025-01-15T10:30:00Z",
    "last_auth_check_at": "2025-01-15T10:30:00Z",
    "live_view_url": "https://live.kernel.com/abc123xyz",
    "login_url": "https://example.com/login",
    "mfa_options": [
      {
        "description": "We'll send a 6-digit code to your phone",
        "label": "Text me a code",
        "target": "***-***-5678",
        "type": "sms"
      }
    ],
    "pending_sso_buttons": [
      {
        "label": "Continue with Google",
        "provider": "google",
        "selector": "xpath=//button[contains(text(), 'Continue with Google')]"
      }
    ],
    "post_login_url": "https://www.netflix.com/browse",
    "profile_name": "my-netflix-profile",
    "save_credentials": true,
    "sign_in_options": [
      {
        "description": "user@company.com",
        "id": "work-account",
        "label": "Work Account (user@company.com)"
      }
    ],
    "sso_provider": "google",
    "status": "AUTHENTICATED"
  }
]

Changes

  • 5629a2109a5aRevision changes
    • warning

      added the new AWAITING_HUMAN_INTERVENTION enum value to the / response property for the response status

    • warning

      added the new human_intervention enum value to the /// response property for the response status

    • info

      added the required property / to the response with the status

  • 03b369edee49Revision changes
    • warning

      removed the optional property /// from the response with the status

    • warning

      added the new optimistic_totp_attempt enum value to the / response property for the response status

    • warning

      added the new requires_customer_input enum value to the / response property for the response status

    • warning

      added the new totp_reauth_allowed enum value to the / response property for the response status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      response property items/browser_telemetry deprecated

    • info

      response property items/proxy_id deprecated

    • info

      added the required property /// to the response with the status