chore: add Managed Auth API planning doc

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 100
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-a6d93dc291278035c96add38bb6150ec2b9ba8bbabb4676e3dbbb8444cf3b1e4.yml
-openapi_spec_hash: 694bcc56d94fd0ff0d1f7b0fc1dae8ba
-config_hash: 62e33cf2ed8fe0b4ceebba63367481ad
+configured_endpoints: 108
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-3fbe762c99e8a120c426ac22bc1fa257c9127d631b12a38a6440a37f52935543.yml
+openapi_spec_hash: 5a190df210ed90b20a71c5061ff43917
+config_hash: 38c9b3b355025daf9bb643040e4af94e

api.md

@@ -203,6 +203,30 @@ Methods:
 - <code title="delete /profiles/{id_or_name}">client.profiles.<a href="./src/resources/profiles.ts">delete</a>(idOrName) -> void</code>
 - <code title="get /profiles/{id_or_name}/download">client.profiles.<a href="./src/resources/profiles.ts">download</a>(idOrName) -> Response</code>
 
+# Auth
+
+## Connections
+
+Types:
+
+- <code><a href="./src/resources/auth/connections.ts">LoginRequest</a></code>
+- <code><a href="./src/resources/auth/connections.ts">LoginResponse</a></code>
+- <code><a href="./src/resources/auth/connections.ts">ManagedAuth</a></code>
+- <code><a href="./src/resources/auth/connections.ts">ManagedAuthCreateRequest</a></code>
+- <code><a href="./src/resources/auth/connections.ts">SubmitFieldsRequest</a></code>
+- <code><a href="./src/resources/auth/connections.ts">SubmitFieldsResponse</a></code>
+- <code><a href="./src/resources/auth/connections.ts">ConnectionFollowResponse</a></code>
+
+Methods:
+
+- <code title="post /auth/connections">client.auth.connections.<a href="./src/resources/auth/connections.ts">create</a>({ ...params }) -> ManagedAuth</code>
+- <code title="get /auth/connections/{id}">client.auth.connections.<a href="./src/resources/auth/connections.ts">retrieve</a>(id) -> ManagedAuth</code>
+- <code title="get /auth/connections">client.auth.connections.<a href="./src/resources/auth/connections.ts">list</a>({ ...params }) -> ManagedAuthsOffsetPagination</code>
+- <code title="delete /auth/connections/{id}">client.auth.connections.<a href="./src/resources/auth/connections.ts">delete</a>(id) -> void</code>
+- <code title="get /auth/connections/{id}/events">client.auth.connections.<a href="./src/resources/auth/connections.ts">follow</a>(id) -> ConnectionFollowResponse</code>
+- <code title="post /auth/connections/{id}/login">client.auth.connections.<a href="./src/resources/auth/connections.ts">login</a>(id, { ...params }) -> LoginResponse</code>
+- <code title="post /auth/connections/{id}/submit">client.auth.connections.<a href="./src/resources/auth/connections.ts">submit</a>(id, { ...params }) -> SubmitFieldsResponse</code>
+
 # Proxies
 
 Types:
@@ -312,15 +336,18 @@ Types:
 
 - <code><a href="./src/resources/credential-providers.ts">CreateCredentialProviderRequest</a></code>
 - <code><a href="./src/resources/credential-providers.ts">CredentialProvider</a></code>
+- <code><a href="./src/resources/credential-providers.ts">CredentialProviderItem</a></code>
 - <code><a href="./src/resources/credential-providers.ts">CredentialProviderTestResult</a></code>
 - <code><a href="./src/resources/credential-providers.ts">UpdateCredentialProviderRequest</a></code>
 - <code><a href="./src/resources/credential-providers.ts">CredentialProviderListResponse</a></code>
+- <code><a href="./src/resources/credential-providers.ts">CredentialProviderListItemsResponse</a></code>
 
 Methods:
 
-- <code title="post /org/credential-providers">client.credentialProviders.<a href="./src/resources/credential-providers.ts">create</a>({ ...params }) -> CredentialProvider</code>
-- <code title="get /org/credential-providers/{id}">client.credentialProviders.<a href="./src/resources/credential-providers.ts">retrieve</a>(id) -> CredentialProvider</code>
-- <code title="patch /org/credential-providers/{id}">client.credentialProviders.<a href="./src/resources/credential-providers.ts">update</a>(id, { ...params }) -> CredentialProvider</code>
-- <code title="get /org/credential-providers">client.credentialProviders.<a href="./src/resources/credential-providers.ts">list</a>() -> CredentialProviderListResponse</code>
-- <code title="delete /org/credential-providers/{id}">client.credentialProviders.<a href="./src/resources/credential-providers.ts">delete</a>(id) -> void</code>
-- <code title="post /org/credential-providers/{id}/test">client.credentialProviders.<a href="./src/resources/credential-providers.ts">test</a>(id) -> CredentialProviderTestResult</code>
+- <code title="post /org/credential_providers">client.credentialProviders.<a href="./src/resources/credential-providers.ts">create</a>({ ...params }) -> CredentialProvider</code>
+- <code title="get /org/credential_providers/{id}">client.credentialProviders.<a href="./src/resources/credential-providers.ts">retrieve</a>(id) -> CredentialProvider</code>
+- <code title="patch /org/credential_providers/{id}">client.credentialProviders.<a href="./src/resources/credential-providers.ts">update</a>(id, { ...params }) -> CredentialProvider</code>
+- <code title="get /org/credential_providers">client.credentialProviders.<a href="./src/resources/credential-providers.ts">list</a>() -> CredentialProviderListResponse</code>
+- <code title="delete /org/credential_providers/{id}">client.credentialProviders.<a href="./src/resources/credential-providers.ts">delete</a>(id) -> void</code>
+- <code title="get /org/credential_providers/{id}/items">client.credentialProviders.<a href="./src/resources/credential-providers.ts">listItems</a>(id) -> CredentialProviderListItemsResponse</code>
+- <code title="post /org/credential_providers/{id}/test">client.credentialProviders.<a href="./src/resources/credential-providers.ts">test</a>(id) -> CredentialProviderTestResult</code>

src/client.ts

@@ -34,6 +34,8 @@ import {
   CreateCredentialProviderRequest,
   CredentialProvider,
   CredentialProviderCreateParams,
+  CredentialProviderItem,
+  CredentialProviderListItemsResponse,
   CredentialProviderListResponse,
   CredentialProviderTestResult,
   CredentialProviderUpdateParams,
@@ -96,6 +98,7 @@ import {
   ProxyRetrieveResponse,
 } from './resources/proxies';
 import { Agents } from './resources/agents/agents';
+import { Auth } from './resources/auth/auth';
 import {
   BrowserCreateParams,
   BrowserCreateResponse,
@@ -891,6 +894,7 @@ export class Kernel {
   invocations: API.Invocations = new API.Invocations(this);
   browsers: API.Browsers = new API.Browsers(this);
   profiles: API.Profiles = new API.Profiles(this);
+  auth: API.Auth = new API.Auth(this);
   proxies: API.Proxies = new API.Proxies(this);
   extensions: API.Extensions = new API.Extensions(this);
   browserPools: API.BrowserPools = new API.BrowserPools(this);
@@ -904,6 +908,7 @@ Kernel.Apps = Apps;
 Kernel.Invocations = Invocations;
 Kernel.Browsers = Browsers;
 Kernel.Profiles = Profiles;
+Kernel.Auth = Auth;
 Kernel.Proxies = Proxies;
 Kernel.Extensions = Extensions;
 Kernel.BrowserPools = BrowserPools;
@@ -979,6 +984,8 @@ export declare namespace Kernel {
     type ProfileCreateParams as ProfileCreateParams,
   };
 
+  export { Auth as Auth };
+
   export {
     Proxies as Proxies,
     type ProxyCreateResponse as ProxyCreateResponse,
@@ -1026,9 +1033,11 @@ export declare namespace Kernel {
     CredentialProviders as CredentialProviders,
     type CreateCredentialProviderRequest as CreateCredentialProviderRequest,
     type CredentialProvider as CredentialProvider,
+    type CredentialProviderItem as CredentialProviderItem,
     type CredentialProviderTestResult as CredentialProviderTestResult,
     type UpdateCredentialProviderRequest as UpdateCredentialProviderRequest,
     type CredentialProviderListResponse as CredentialProviderListResponse,
+    type CredentialProviderListItemsResponse as CredentialProviderListItemsResponse,
     type CredentialProviderCreateParams as CredentialProviderCreateParams,
     type CredentialProviderUpdateParams as CredentialProviderUpdateParams,
   };

src/resources/agents/auth/auth.ts

@@ -19,46 +19,33 @@ export class Auth extends APIResource {
   invocations: InvocationsAPI.Invocations = new InvocationsAPI.Invocations(this._client);
 
   /**
-   * Creates a new auth agent for the specified domain and profile combination, or
-   * returns an existing one if it already exists. This is idempotent - calling with
-   * the same domain and profile will return the same agent. Does NOT start an
-   * invocation - use POST /agents/auth/invocations to start an auth flow.
+   * **Deprecated: Use POST /auth/connections instead.** Creates a new auth agent for
+   * the specified domain and profile combination, or returns an existing one if it
+   * already exists. This is idempotent - calling with the same domain and profile
+   * will return the same agent. Does NOT start an invocation - use POST
+   * /agents/auth/invocations to start an auth flow.
    *
-   * @example
-   * ```ts
-   * const authAgent = await client.agents.auth.create({
-   *   domain: 'netflix.com',
-   *   profile_name: 'user-123',
-   * });
-   * ```
+   * @deprecated
    */
   create(body: AuthCreateParams, options?: RequestOptions): APIPromise<AuthAgent> {
     return this._client.post('/agents/auth', { body, ...options });
   }
 
   /**
-   * Retrieve an auth agent by its ID. Returns the current authentication status of
-   * the managed profile.
+   * **Deprecated: Use GET /auth/connections/{id} instead.** Retrieve an auth agent
+   * by its ID. Returns the current authentication status of the managed profile.
    *
-   * @example
-   * ```ts
-   * const authAgent = await client.agents.auth.retrieve('id');
-   * ```
+   * @deprecated
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<AuthAgent> {
     return this._client.get(path`/agents/auth/${id}`, options);
   }
 
   /**
-   * List auth agents with optional filters for profile_name and domain.
+   * **Deprecated: Use GET /auth/connections instead.** List auth agents with
+   * optional filters for profile_name and domain.
    *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const authAgent of client.agents.auth.list()) {
-   *   // ...
-   * }
-   * ```
+   * @deprecated
    */
   list(
     query: AuthListParams | null | undefined = {},
@@ -68,16 +55,14 @@ export class Auth extends APIResource {
   }
 
   /**
-   * Deletes an auth agent and terminates its workflow. This will:
+   * **Deprecated: Use DELETE /auth/connections/{id} instead.** Deletes an auth agent
+   * and terminates its workflow. This will:
    *
    * - Soft delete the auth agent record
    * - Gracefully terminate the agent's Temporal workflow
    * - Cancel any in-progress invocations
    *
-   * @example
-   * ```ts
-   * await client.agents.auth.delete('id');
-   * ```
+   * @deprecated
    */
   delete(id: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/agents/auth/${id}`, {
@@ -126,13 +111,12 @@ export interface AgentAuthInvocationResponse {
     | 'expired';
 
   /**
-   * The invocation type:
+   * The session type:
    *
-   * - login: First-time authentication
-   * - reauth: Re-authentication for previously authenticated agents
-   * - auto_login: Legacy type (no longer created, kept for backward compatibility)
+   * - login: User-initiated authentication
+   * - reauth: System-triggered re-authentication (via health check)
    */
-  type: 'login' | 'auto_login' | 'reauth';
+  type: 'login' | 'reauth';
 
   /**
    * Error message explaining why the invocation failed (present when status=FAILED)
@@ -188,9 +172,9 @@ export namespace AgentAuthInvocationResponse {
     label: string;
 
     /**
-     * The MFA delivery method type
+     * The MFA delivery method type (includes password for auth method selection pages)
      */
-    type: 'sms' | 'call' | 'email' | 'totp' | 'push' | 'security_key';
+    type: 'sms' | 'call' | 'email' | 'totp' | 'push' | 'password';
 
     /**
      * Additional instructions from the site
@@ -263,6 +247,21 @@ export interface AuthAgent {
    * Additional domains that are valid for this auth agent's authentication 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
    */
   allowed_domains?: Array<string>;
 
@@ -273,14 +272,19 @@ export interface AuthAgent {
   can_reauth?: boolean;
 
   /**
-   * ID of the linked credential for automatic re-authentication
+   * Reference to credentials for managed auth. Use one of:
+   *
+   * - { name } for Kernel credentials
+   * - { provider, path } for external provider item
+   * - { provider, auto: true } for external provider domain lookup
    */
-  credential_id?: string;
+  credential?: AuthAgent.Credential;
 
   /**
-   * Name of the linked credential for automatic re-authentication
+   * ID of the linked Kernel credential for automatic re-authentication (deprecated,
+   * use credential)
    */
-  credential_name?: string;
+  credential_id?: string;
 
   /**
    * Whether this auth agent has stored selectors for deterministic re-authentication
@@ -299,6 +303,37 @@ export interface AuthAgent {
   post_login_url?: string;
 }
 
+export namespace AuthAgent {
+  /**
+   * Reference to credentials for managed auth. Use one of:
+   *
+   * - { name } for Kernel credentials
+   * - { provider, path } for external provider item
+   * - { provider, auto: true } for external provider domain lookup
+   */
+  export interface Credential {
+    /**
+     * If true, lookup by domain from the specified provider
+     */
+    auto?: boolean;
+
+    /**
+     * Kernel credential name
+     */
+    name?: string;
+
+    /**
+     * Provider-specific path (e.g., "VaultName/ItemName" for 1Password)
+     */
+    path?: string;
+
+    /**
+     * External provider name (e.g., "my-1p")
+     */
+    provider?: string;
+  }
+}
+
 /**
  * Request to create or find an auth agent
  */
@@ -317,6 +352,21 @@ export interface AuthAgentCreateRequest {
    * Additional domains that are valid for this auth agent's authentication 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
    */
   allowed_domains?: Array<string>;
 
@@ -393,13 +443,12 @@ export interface AuthAgentInvocationCreateResponse {
   invocation_id: string;
 
   /**
-   * The invocation type:
+   * The session type:
    *
-   * - login: First-time authentication
-   * - reauth: Re-authentication for previously authenticated agents
-   * - auto_login: Legacy type (no longer created, kept for backward compatibility)
+   * - login: User-initiated authentication
+   * - reauth: System-triggered re-authentication (via health check)
    */
-  type: 'login' | 'auto_login' | 'reauth';
+  type: 'login' | 'reauth';
 }
 
 /**
@@ -426,6 +475,12 @@ export interface DiscoveredField {
    */
   type: 'text' | 'email' | 'password' | 'tel' | 'number' | 'url' | 'code' | 'totp';
 
+  /**
+   * If this field is associated with an MFA option, the type of that option (e.g.,
+   * password field linked to "Enter password" option)
+   */
+  linked_mfa_type?: 'sms' | 'call' | 'email' | 'totp' | 'push' | 'password' | null;
+
   /**
    * Field placeholder
    */
@@ -452,6 +507,21 @@ export interface AuthCreateParams {
    * Additional domains that are valid for this auth agent's authentication 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
    */
   allowed_domains?: Array<string>;