> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-changelog-august-13.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Start login flow > Starts a login flow for the auth connection. Returns immediately with a hosted URL for the user to complete authentication, or triggers automatic re-auth if credentials are stored. ## OpenAPI ````yaml https://api.onkernel.com/spec.json post /auth/connections/{id}/login openapi: 3.1.0 info: description: Developer tools and cloud infrastructure for AI agents to use web browsers title: Kernel API version: 0.1.0 servers: - description: API Server url: https://api.onkernel.com security: - bearerAuth: [] tags: - description: Create and manage browser sessions. name: Browsers - description: Control mouse, keyboard, and screen on the browser instance. name: Browser Computer Controls - description: Execute Playwright code against the browser instance. name: Browser Playwright - description: Read, write, and manage files on the browser instance. name: Browser Filesystem - description: Execute and manage processes on the browser instance. name: Browser Processes - description: Record and manage browser session video replays. name: Browser Replays - description: Stream logs from the browser instance. name: Browser Logs - description: Stream live telemetry events from a browser session. name: Browser Telemetry - description: Create, list, retrieve, and delete browser profiles. name: Profiles - description: Create and manage proxy configurations for routing browser traffic. name: Proxies - description: Create, list, retrieve, and delete browser extensions. name: Extensions - description: Create and manage browser pools for acquiring and releasing browsers. name: Browser Pools - description: Inspect the identity and authorization context for the current request. name: Authentication - description: >- Create and manage auth connections for automated credential capture and login. name: Managed Auth - description: Create and manage credentials for authentication. name: Credentials - description: Configure external credential providers like 1Password. name: Credential Providers - description: List applications and versions. name: Apps - description: Create and manage app deployments and stream deployment events. name: Deployments - description: Invoke actions and stream or query invocation status and events. name: Invocations - description: Read and manage organization-level limits. name: Organization - description: | Create and manage projects for resource isolation within an organization. When projects are disabled for the organization, project operations return `404` with code `projects_disabled`. name: Projects - description: Create and manage API keys for organization and project-scoped access. name: API Keys - description: Read audit log records for the authenticated organization. name: Audit Logs - description: Resolve browser and proxy recommendations for bot-protected sites. name: Site Configs paths: /auth/connections/{id}/login: post: tags: - Managed Auth summary: Start login flow description: >- Starts a login flow for the auth connection. Returns immediately with a hosted URL for the user to complete authentication, or triggers automatic re-auth if credentials are stored. operationId: postAuthConnectionsLogin parameters: - description: Auth connection ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/LoginRequest' required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/LoginResponse' description: Login flow started '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: Login flow already in progress '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: schemas: LoginRequest: additionalProperties: false description: Request to start a login flow properties: browser: $ref: '#/components/schemas/ManagedAuthBrowserConfig' description: >- Browser configuration override for this login. Omitted properties inherit the connection defaults. browser_telemetry: $ref: '#/components/schemas/BrowserTelemetryRequestConfig' deprecated: true description: >- Deprecated. Use browser.telemetry. Retained during migration for existing clients. nullable: true proxy: $ref: '#/components/schemas/ProxyRef' deprecated: true description: >- Deprecated. Use browser.proxy. Retained during migration for existing clients. record_session: description: >- Override the connection's default for recording this login's browser session. When omitted, the connection's record_session default is used. example: true type: boolean type: object LoginResponse: additionalProperties: false description: Response from starting a login flow properties: flow_expires_at: description: When the login flow expires example: '2025-11-05T20:00:00Z' format: date-time type: string flow_type: description: Type of login flow started enum: - LOGIN - REAUTH example: LOGIN type: string handoff_code: description: One-time code for handoff (internal use) example: aBcD123EfGh456IjKl789MnOp012QrStUvWxYzAbCdEf type: string hosted_url: description: URL to redirect user to for login example: https://auth.kernel.com/login/abc123xyz format: uri type: string id: description: Auth connection ID example: ma_abc123xyz type: string live_view_url: description: Browser live view URL for watching the login flow example: https://live.onkernel.com/abc123xyz format: uri type: string required: - id - flow_type - hosted_url - flow_expires_at type: object Error: properties: code: description: Application-specific error code (machine-readable) example: bad_request type: string details: description: Additional error details (for multiple errors) items: $ref: '#/components/schemas/ErrorDetail' type: array inner_error: $ref: '#/components/schemas/ErrorDetail' message: description: Human-readable error description for debugging example: 'Missing required field: app_name' type: string required: - code - message type: object ManagedAuthBrowserConfig: additionalProperties: false description: >- Browser configuration applied to browser sessions created for a managed auth connection. Managed auth controls the profile, headless mode, timeout, start URL, kiosk mode, and viewport. properties: proxy: $ref: '#/components/schemas/BrowserProxyConfig' description: >- Proxy configuration for managed auth browser sessions. Omit on create to derive the default from stealth, or on update and login to preserve or inherit the connection default. stealth: description: >- Whether managed auth browser sessions use stealth mode. Defaults to true when omitted. example: false type: boolean telemetry: $ref: '#/components/schemas/BrowserTelemetryRequestConfig' description: >- Browser telemetry configuration using the same semantics as browser create. nullable: true type: object BrowserTelemetryRequestConfig: description: Telemetry request configuration for a browser session. properties: browser: $ref: '#/components/schemas/BrowserTelemetryCategoriesConfig' description: >- Per-category capture flags. The operational categories (control, connection, system, captcha) are captured whenever telemetry is enabled; set one to enabled=false to opt out. The CDP categories (console, network, page, interaction) and screenshot are off by default; set enabled=true to opt in. On create, provided categories layer onto the default set. On update, provided categories merge onto the session's current config; when no telemetry is active this falls back to the default set (matching create). If browser is omitted or empty, the default set is used. A browser config that disables every category stops capture on update and starts no capture on create. enabled: description: >- Request shortcut for browser telemetry capture. True enables capture; with no browser category settings it captures the default set (control, connection, system, captcha), and any browser category settings are layered onto that default set. On update, enabled=true resolves the config fresh from the default set plus any provided categories, replacing the session's current selection rather than merging onto it; omit enabled to merge categories onto the current selection instead. False stops capture on update and starts no capture on create. enabled=false cannot be combined with browser category settings. type: boolean export: $ref: '#/components/schemas/BrowserTelemetryExportRequestConfig' description: >- Where to export this session's captured telemetry. Omit to capture without exporting. type: object ProxyRef: description: > 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. oneOf: - required: - id - required: - name properties: id: description: Proxy ID type: string name: description: Proxy name type: string type: object ErrorDetail: properties: code: description: Lower-level error code providing more specific detail example: invalid_input type: string message: description: Further detail about the error example: Provided version string is not semver compliant type: string type: object BrowserProxyConfig: additionalProperties: false description: > Browser proxy configuration. Provide exactly one of mode, id, or name; an empty object is invalid. Set mode to direct for no proxy regardless of stealth. Set mode to default to use the browser's stealth-derived default: Kernel's default stealth proxy when stealth=true, or direct egress when stealth=false. Select id or name to use that proxy regardless of stealth. The selected proxy must be in the same project as the browser. Names must match exactly one active proxy; use id for stable references. Proxy configuration changes only egress and does not change stealth or CAPTCHA solver behavior. A stealth browser using mode=direct still runs in stealth mode with the CAPTCHA solver enabled. When proxy is omitted on browser creation, stealth browsers use Kernel's default stealth proxy and non-stealth browsers use direct egress. When omitted on update, the current configuration is unchanged. oneOf: - required: - mode - required: - id - required: - name properties: id: description: Proxy ID. minLength: 1 type: string mode: $ref: '#/components/schemas/BrowserProxyMode' name: description: Proxy name. Must match exactly one active proxy in the project. minLength: 1 type: string type: object BrowserTelemetryCategoriesConfig: description: >- Per-category telemetry capture settings layered onto the default set. The operational signals (control, connection, system, captcha) are on by default and are opt-out: set one to enabled=false to stop capturing it. The CDP categories (console, network, page, interaction) and screenshot are off by default and are opt-in: set enabled=true to capture them. properties: captcha: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: Captcha solve attempt outcomes. On by default. connection: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Client attach/detach lifecycle for the CDP proxy and live view. On by default. console: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Console output (log, warn, error) and uncaught exceptions. CDP category; off by default. control: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Agent-driven actions against the browser, such as inbound calls to the in-VM API. On by default. interaction: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- User interaction events including clicks, keydowns, and scroll-settled events. CDP category; off by default. network: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- HTTP request and response metadata including URL, method, status code, and timing. Request post data is forwarded as-is from CDP. Text response bodies are truncated at 8 KB for structured types (JSON, XML, form data) and 4 KB for other text types. Binary responses (images, fonts, media) are excluded. CDP category; off by default. page: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Page lifecycle events including navigation, DOMContentLoaded, load, layout shifts, and LCP. CDP category; off by default. screenshot: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Periodic base64-encoded viewport screenshots. High volume; off by default and must be opted into. system: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Browser VM health, such as out-of-memory kills and managed-service crashes. On by default. type: object BrowserTelemetryExportRequestConfig: description: >- Export destinations for a session's captured telemetry, by protocol. Honored when creating a browser, including the browser a managed auth connection creates for a login. Browser pools do not support export and reject it; on a browser update it is ignored, so the session keeps the destination it was created with. properties: otlp: $ref: '#/components/schemas/BrowserTelemetryOTLPExportRequestConfig' description: >- Export captured telemetry over OTLP to one of the org's configured destinations. type: object BrowserProxyMode: description: > Proxy egress mode. direct forces no proxy regardless of stealth. default uses the browser's stealth-derived default: Kernel's default stealth proxy when stealth=true, or direct egress when stealth=false. default is primarily useful on browser update to restore the browser default after selected-proxy egress. enum: - direct - default type: string x-enum-varnames: - Direct - Default BrowserTelemetryCategoryConfig: description: Per-category telemetry configuration. properties: enabled: description: >- Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in. type: boolean type: object BrowserTelemetryOTLPExportRequestConfig: description: OTLP export settings for a browser session. properties: destination: $ref: '#/components/schemas/OTLPDestinationRef' description: >- OTLP destination to export this session's captured telemetry to. Provide either id or name. Requires telemetry capture to be enabled. enabled: description: >- Whether to export captured telemetry over OTLP. Setting destination implies enabled=true, so this only needs to be set explicitly to disable export (enabled=false with a destination is rejected). type: boolean type: object OTLPDestinationRef: description: > OTLP destination selection. Provide either id or name. The destination must belong to the caller's org. When selecting by name, the name must match exactly one destination in the org. Ambiguous names return a 400; use id for stable references. oneOf: - required: - id - required: - name properties: id: description: OTLP destination ID type: string name: description: OTLP destination name type: string type: object responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad Request – invalid input Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unauthorized – missing or invalid authorization token Forbidden: content: application/json: schema: $ref: '#/components/schemas/Error' description: Forbidden – insufficient permissions or plan NotFound: content: application/json: schema: $ref: '#/components/schemas/Error' description: Resource not found InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error securitySchemes: bearerAuth: scheme: bearer type: http ````