Create auth connection

POST/auth/connections

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.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to create an auth connection for a profile and domain

domain*string

Domain for authentication

profile_name*string

Name of the profile to manage authentication for. If the profile does not exist, it is created automatically.

login_url?string

Optional login page URL to skip discovery

Formaturi

proxy?|

Proxy selection. Provide either id or name. The proxy must be in the same project as the resource referencing it. When selecting by name, the name must match exactly one active proxy in the project. Ambiguous names return a 400; use id for stable references.

credential?

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

allowed_domains?array<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

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

Range300 <= value <= 86400

health_checks?boolean

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.

Defaulttrue

auto_reauth?boolean

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.

Defaulttrue

save_credentials?boolean

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

Defaulttrue

record_session?boolean

Whether to record browser sessions for this connection by default. Useful for debugging. Can be overridden per-login. Defaults to false.

Defaultfalse

Response Body

`application/json`

curl -X POST "https://example.com/auth/connections" \  -H "Content-Type: application/json" \  -d '{    "domain": "string",    "profile_name": "string"  }'

{  "id": "string",  "profile_name": "string",  "domain": "string",  "status": "AUTHENTICATED",  "last_auth_check_at": "2019-08-24T14:15:22Z",  "last_auth_at": "2019-08-24T14:15:22Z",  "credential": {    "name": "string",    "provider": "string",    "path": "string",    "auto": true  },  "can_reauth": true,  "can_reauth_reason": "external_credential",  "proxy_id": "string",  "allowed_domains": [    "string"  ],  "login_url": "http://example.com",  "post_login_url": "http://example.com",  "flow_status": "IN_PROGRESS",  "flow_step": "DISCOVERING",  "flow_type": "LOGIN",  "flow_expires_at": "2019-08-24T14:15:22Z",  "fields": [    {      "id": "string",      "ref": "string",      "type": "identifier",      "label": "string",      "required": true,      "observed_selector": "string"    }  ],  "choices": [    {      "id": "string",      "type": "mfa_method",      "label": "string",      "description": "string",      "observed_selector": "string"    }  ],  "discovered_fields": [    {      "name": "string",      "type": "text",      "label": "string",      "placeholder": "string",      "required": true,      "selector": "string",      "linked_mfa_type": "sms",      "hint": "string"    }  ],  "mfa_options": [    {      "type": "sms",      "label": "string",      "target": "string",      "description": "string"    }  ],  "sign_in_options": [    {      "id": "string",      "label": "string",      "description": "string"    }  ],  "pending_sso_buttons": [    {      "selector": "string",      "provider": "string",      "label": "string"    }  ],  "external_action_message": "string",  "website_error": "string",  "sso_provider": "string",  "error_message": "string",  "error_code": "string",  "hosted_url": "http://example.com",  "live_view_url": "http://example.com",  "browser_session_id": "string",  "health_check_interval": 300,  "health_checks": true,  "auto_reauth": true,  "save_credentials": true,  "record_session": true}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

{  "code": "string",  "message": "string",  "existing_id": "string"}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

409application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`