@workos-inc/node 8.0.0-rc.6 → 8.0.0-rc.8

package/lib/sso/sso.cjs

@@ -1,10 +1,10 @@
-const require_client_sso = require('../client/sso.cjs');
+const require_common_utils_pagination = require('../common/utils/pagination.cjs');
 const require_sso_serializers_connection_serializer = require('./serializers/connection.serializer.cjs');
 const require_sso_serializers_list_connections_options_serializer = require('./serializers/list-connections-options.serializer.cjs');
 const require_sso_serializers_profile_serializer = require('./serializers/profile.serializer.cjs');
 const require_sso_serializers_profile_and_token_serializer = require('./serializers/profile-and-token.serializer.cjs');
-const require_common_utils_pagination = require('../common/utils/pagination.cjs');
 const require_common_utils_fetch_and_deserialize = require('../common/utils/fetch-and-deserialize.cjs');
+const require_common_utils_query_string = require('../common/utils/query-string.cjs');
 
 //#region src/sso/sso.ts
 var SSO = class {
@@ -18,23 +18,105 @@ var SSO = class {
 		await this.workos.delete(`/connections/${id}`);
 	}
 	getAuthorizationUrl(options) {
-		return require_client_sso.getAuthorizationUrl({
-			...options,
-			baseURL: this.workos.baseURL
+		const { codeChallenge, codeChallengeMethod, connection, clientId, domainHint, loginHint, organization, provider, providerQueryParams, providerScopes, redirectUri, state } = options;
+		if (!provider && !connection && !organization) throw new TypeError(`Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`);
+		const query = require_common_utils_query_string.toQueryString({
+			code_challenge: codeChallenge,
+			code_challenge_method: codeChallengeMethod,
+			connection,
+			organization,
+			domain_hint: domainHint,
+			login_hint: loginHint,
+			provider,
+			provider_query_params: providerQueryParams,
+			provider_scopes: providerScopes,
+			client_id: clientId,
+			redirect_uri: redirectUri,
+			response_type: "code",
+			state
+		});
+		return `${this.workos.baseURL}/sso/authorize?${query}`;
+	}
+	/**
+	* Generates an authorization URL with PKCE parameters automatically generated.
+	* Use this for public clients (CLI apps, Electron, mobile) that cannot
+	* securely store a client secret.
+	*
+	* @returns Object containing url, state, and codeVerifier
+	*
+	* @example
+	* ```typescript
+	* const { url, state, codeVerifier } = await workos.sso.getAuthorizationUrlWithPKCE({
+	*   connection: 'conn_123',
+	*   clientId: 'client_123',
+	*   redirectUri: 'myapp://callback',
+	* });
+	*
+	* // Store state and codeVerifier securely, then redirect user to url
+	* // After callback, exchange the code:
+	* const { profile, accessToken } = await workos.sso.getProfileAndToken({
+	*   code: authorizationCode,
+	*   codeVerifier,
+	*   clientId: 'client_123',
+	* });
+	* ```
+	*/
+	async getAuthorizationUrlWithPKCE(options) {
+		const { connection, clientId, domainHint, loginHint, organization, provider, providerQueryParams, providerScopes, redirectUri } = options;
+		if (!provider && !connection && !organization) throw new TypeError(`Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`);
+		const pkce = await this.workos.pkce.generate();
+		const state = this.workos.pkce.generateCodeVerifier(43);
+		const query = require_common_utils_query_string.toQueryString({
+			code_challenge: pkce.codeChallenge,
+			code_challenge_method: "S256",
+			connection,
+			organization,
+			domain_hint: domainHint,
+			login_hint: loginHint,
+			provider,
+			provider_query_params: providerQueryParams,
+			provider_scopes: providerScopes,
+			client_id: clientId,
+			redirect_uri: redirectUri,
+			response_type: "code",
+			state
 		});
+		return {
+			url: `${this.workos.baseURL}/sso/authorize?${query}`,
+			state,
+			codeVerifier: pkce.codeVerifier
+		};
 	}
 	async getConnection(id) {
 		const { data } = await this.workos.get(`/connections/${id}`);
 		return require_sso_serializers_connection_serializer.deserializeConnection(data);
 	}
-	async getProfileAndToken({ code, clientId }) {
+	/**
+	* Exchange an authorization code for a profile and access token.
+	*
+	* Auto-detects public vs confidential client mode:
+	* - If codeVerifier is provided: Uses PKCE flow (public client)
+	* - If no codeVerifier: Uses client_secret from API key (confidential client)
+	* - If both: Uses both client_secret AND codeVerifier (confidential client with PKCE)
+	*
+	* Using PKCE with confidential clients is recommended by OAuth 2.1 for defense
+	* in depth and provides additional CSRF protection on the authorization flow.
+	*
+	* @throws Error if neither codeVerifier nor API key is available
+	*/
+	async getProfileAndToken({ code, clientId, codeVerifier }) {
+		if (codeVerifier !== void 0 && codeVerifier.trim() === "") throw new TypeError("codeVerifier cannot be an empty string. Generate a valid PKCE pair using workos.pkce.generate().");
+		const hasApiKey = !!this.workos.key;
+		const hasPKCE = !!codeVerifier;
+		if (!hasPKCE && !hasApiKey) throw new TypeError("getProfileAndToken requires either a codeVerifier (for public clients) or an API key configured on the WorkOS instance (for confidential clients).");
 		const form = new URLSearchParams({
 			client_id: clientId,
-			client_secret: this.workos.key,
 			grant_type: "authorization_code",
 			code
 		});
-		const { data } = await this.workos.post("/sso/token", form);
+		if (hasPKCE) form.set("code_verifier", codeVerifier);
+		if (hasApiKey) form.set("client_secret", this.workos.key);
+		const { data } = await this.workos.post("/sso/token", form, { skipApiKeyCheck: !hasApiKey });
 		return require_sso_serializers_profile_and_token_serializer.deserializeProfileAndToken(data);
 	}
 	async getProfile({ accessToken }) {

package/lib/sso/sso.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"sso.cjs","names":["workos: WorkOS","AutoPaginatable","fetchAndDeserialize","deserializeConnection","serializeListConnectionsOptions","deserializeProfileAndToken","deserializeProfile"],"sources":["../../src/sso/sso.ts"],"sourcesContent":["import * as clientSSO from '../client/sso';\nimport { UnknownRecord } from '../common/interfaces/unknown-record.interface';\nimport { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';\nimport { AutoPaginatable } from '../common/utils/pagination';\nimport { WorkOS } from '../workos';\nimport {\n  Connection,\n  ConnectionResponse,\n  GetProfileAndTokenOptions,\n  GetProfileOptions,\n  ListConnectionsOptions,\n  Profile,\n  ProfileAndToken,\n  ProfileAndTokenResponse,\n  ProfileResponse,\n  SSOAuthorizationURLOptions,\n  SerializedListConnectionsOptions,\n} from './interfaces';\nimport {\n  deserializeConnection,\n  deserializeProfile,\n  deserializeProfileAndToken,\n  serializeListConnectionsOptions,\n} from './serializers';\n\nexport class SSO {\n  constructor(private readonly workos: WorkOS) {}\n\n  async listConnections(\n    options?: ListConnectionsOptions,\n  ): Promise<AutoPaginatable<Connection, SerializedListConnectionsOptions>> {\n    return new AutoPaginatable(\n      await fetchAndDeserialize<ConnectionResponse, Connection>(\n        this.workos,\n        '/connections',\n        deserializeConnection,\n        options ? serializeListConnectionsOptions(options) : undefined,\n      ),\n      (params) =>\n        fetchAndDeserialize<ConnectionResponse, Connection>(\n          this.workos,\n          '/connections',\n          deserializeConnection,\n          params,\n        ),\n      options ? serializeListConnectionsOptions(options) : undefined,\n    );\n  }\n  async deleteConnection(id: string) {\n    await this.workos.delete(`/connections/${id}`);\n  }\n\n  getAuthorizationUrl(options: SSOAuthorizationURLOptions): string {\n    // Delegate to client implementation\n    return clientSSO.getAuthorizationUrl({\n      ...options,\n      baseURL: this.workos.baseURL,\n    });\n  }\n\n  async getConnection(id: string): Promise<Connection> {\n    const { data } = await this.workos.get<ConnectionResponse>(\n      `/connections/${id}`,\n    );\n\n    return deserializeConnection(data);\n  }\n\n  async getProfileAndToken<\n    CustomAttributesType extends UnknownRecord = UnknownRecord,\n  >({\n    code,\n    clientId,\n  }: GetProfileAndTokenOptions): Promise<\n    ProfileAndToken<CustomAttributesType>\n  > {\n    const form = new URLSearchParams({\n      client_id: clientId,\n      client_secret: this.workos.key as string,\n      grant_type: 'authorization_code',\n      code,\n    });\n\n    const { data } = await this.workos.post<\n      ProfileAndTokenResponse<CustomAttributesType>\n    >('/sso/token', form);\n\n    return deserializeProfileAndToken(data);\n  }\n\n  async getProfile<CustomAttributesType extends UnknownRecord = UnknownRecord>({\n    accessToken,\n  }: GetProfileOptions): Promise<Profile<CustomAttributesType>> {\n    const { data } = await this.workos.get<\n      ProfileResponse<CustomAttributesType>\n    >('/sso/profile', {\n      accessToken,\n    });\n\n    return deserializeProfile(data);\n  }\n}\n"],"mappings":";;;;;;;;;AAyBA,IAAa,MAAb,MAAiB;CACf,YAAY,AAAiBA,QAAgB;EAAhB;;CAE7B,MAAM,gBACJ,SACwE;AACxE,SAAO,IAAIC,gDACT,MAAMC,+DACJ,KAAK,QACL,gBACAC,qEACA,UAAUC,4FAAgC,QAAQ,GAAG,OACtD,GACA,WACCF,+DACE,KAAK,QACL,gBACAC,qEACA,OACD,EACH,UAAUC,4FAAgC,QAAQ,GAAG,OACtD;;CAEH,MAAM,iBAAiB,IAAY;AACjC,QAAM,KAAK,OAAO,OAAO,gBAAgB,KAAK;;CAGhD,oBAAoB,SAA6C;AAE/D,gDAAqC;GACnC,GAAG;GACH,SAAS,KAAK,OAAO;GACtB,CAAC;;CAGJ,MAAM,cAAc,IAAiC;EACnD,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,IACjC,gBAAgB,KACjB;AAED,SAAOD,oEAAsB,KAAK;;CAGpC,MAAM,mBAEJ,EACA,MACA,YAGA;EACA,MAAM,OAAO,IAAI,gBAAgB;GAC/B,WAAW;GACX,eAAe,KAAK,OAAO;GAC3B,YAAY;GACZ;GACD,CAAC;EAEF,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,KAEjC,cAAc,KAAK;AAErB,SAAOE,gFAA2B,KAAK;;CAGzC,MAAM,WAAuE,EAC3E,eAC4D;EAC5D,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,IAEjC,gBAAgB,EAChB,aACD,CAAC;AAEF,SAAOC,8DAAmB,KAAK"}
+{"version":3,"file":"sso.cjs","names":["workos: WorkOS","AutoPaginatable","fetchAndDeserialize","deserializeConnection","serializeListConnectionsOptions","toQueryString","deserializeProfileAndToken","deserializeProfile"],"sources":["../../src/sso/sso.ts"],"sourcesContent":["import { UnknownRecord } from '../common/interfaces/unknown-record.interface';\nimport { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';\nimport { AutoPaginatable } from '../common/utils/pagination';\nimport { toQueryString } from '../common/utils/query-string';\nimport { WorkOS } from '../workos';\nimport {\n  Connection,\n  ConnectionResponse,\n  GetProfileAndTokenOptions,\n  GetProfileOptions,\n  ListConnectionsOptions,\n  Profile,\n  ProfileAndToken,\n  ProfileAndTokenResponse,\n  ProfileResponse,\n  SSOAuthorizationURLOptions,\n  SSOPKCEAuthorizationURLResult,\n  SerializedListConnectionsOptions,\n} from './interfaces';\nimport {\n  deserializeConnection,\n  deserializeProfile,\n  deserializeProfileAndToken,\n  serializeListConnectionsOptions,\n} from './serializers';\n\nexport class SSO {\n  constructor(private readonly workos: WorkOS) {}\n\n  async listConnections(\n    options?: ListConnectionsOptions,\n  ): Promise<AutoPaginatable<Connection, SerializedListConnectionsOptions>> {\n    return new AutoPaginatable(\n      await fetchAndDeserialize<ConnectionResponse, Connection>(\n        this.workos,\n        '/connections',\n        deserializeConnection,\n        options ? serializeListConnectionsOptions(options) : undefined,\n      ),\n      (params) =>\n        fetchAndDeserialize<ConnectionResponse, Connection>(\n          this.workos,\n          '/connections',\n          deserializeConnection,\n          params,\n        ),\n      options ? serializeListConnectionsOptions(options) : undefined,\n    );\n  }\n  async deleteConnection(id: string) {\n    await this.workos.delete(`/connections/${id}`);\n  }\n\n  getAuthorizationUrl(options: SSOAuthorizationURLOptions): string {\n    const {\n      codeChallenge,\n      codeChallengeMethod,\n      connection,\n      clientId,\n      domainHint,\n      loginHint,\n      organization,\n      provider,\n      providerQueryParams,\n      providerScopes,\n      redirectUri,\n      state,\n    } = options;\n\n    if (!provider && !connection && !organization) {\n      throw new TypeError(\n        `Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`,\n      );\n    }\n\n    const query = toQueryString({\n      code_challenge: codeChallenge,\n      code_challenge_method: codeChallengeMethod,\n      connection,\n      organization,\n      domain_hint: domainHint,\n      login_hint: loginHint,\n      provider,\n      provider_query_params: providerQueryParams,\n      provider_scopes: providerScopes,\n      client_id: clientId,\n      redirect_uri: redirectUri,\n      response_type: 'code',\n      state,\n    });\n\n    return `${this.workos.baseURL}/sso/authorize?${query}`;\n  }\n\n  /**\n   * Generates an authorization URL with PKCE parameters automatically generated.\n   * Use this for public clients (CLI apps, Electron, mobile) that cannot\n   * securely store a client secret.\n   *\n   * @returns Object containing url, state, and codeVerifier\n   *\n   * @example\n   * ```typescript\n   * const { url, state, codeVerifier } = await workos.sso.getAuthorizationUrlWithPKCE({\n   *   connection: 'conn_123',\n   *   clientId: 'client_123',\n   *   redirectUri: 'myapp://callback',\n   * });\n   *\n   * // Store state and codeVerifier securely, then redirect user to url\n   * // After callback, exchange the code:\n   * const { profile, accessToken } = await workos.sso.getProfileAndToken({\n   *   code: authorizationCode,\n   *   codeVerifier,\n   *   clientId: 'client_123',\n   * });\n   * ```\n   */\n  async getAuthorizationUrlWithPKCE(\n    options: Omit<\n      SSOAuthorizationURLOptions,\n      'codeChallenge' | 'codeChallengeMethod' | 'state'\n    >,\n  ): Promise<SSOPKCEAuthorizationURLResult> {\n    const {\n      connection,\n      clientId,\n      domainHint,\n      loginHint,\n      organization,\n      provider,\n      providerQueryParams,\n      providerScopes,\n      redirectUri,\n    } = options;\n\n    if (!provider && !connection && !organization) {\n      throw new TypeError(\n        `Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`,\n      );\n    }\n\n    // Generate PKCE parameters\n    const pkce = await this.workos.pkce.generate();\n\n    // Generate secure random state\n    const state = this.workos.pkce.generateCodeVerifier(43);\n\n    const query = toQueryString({\n      code_challenge: pkce.codeChallenge,\n      code_challenge_method: 'S256',\n      connection,\n      organization,\n      domain_hint: domainHint,\n      login_hint: loginHint,\n      provider,\n      provider_query_params: providerQueryParams,\n      provider_scopes: providerScopes,\n      client_id: clientId,\n      redirect_uri: redirectUri,\n      response_type: 'code',\n      state,\n    });\n\n    const url = `${this.workos.baseURL}/sso/authorize?${query}`;\n\n    return { url, state, codeVerifier: pkce.codeVerifier };\n  }\n\n  async getConnection(id: string): Promise<Connection> {\n    const { data } = await this.workos.get<ConnectionResponse>(\n      `/connections/${id}`,\n    );\n\n    return deserializeConnection(data);\n  }\n\n  /**\n   * Exchange an authorization code for a profile and access token.\n   *\n   * Auto-detects public vs confidential client mode:\n   * - If codeVerifier is provided: Uses PKCE flow (public client)\n   * - If no codeVerifier: Uses client_secret from API key (confidential client)\n   * - If both: Uses both client_secret AND codeVerifier (confidential client with PKCE)\n   *\n   * Using PKCE with confidential clients is recommended by OAuth 2.1 for defense\n   * in depth and provides additional CSRF protection on the authorization flow.\n   *\n   * @throws Error if neither codeVerifier nor API key is available\n   */\n  async getProfileAndToken<\n    CustomAttributesType extends UnknownRecord = UnknownRecord,\n  >({\n    code,\n    clientId,\n    codeVerifier,\n  }: GetProfileAndTokenOptions): Promise<\n    ProfileAndToken<CustomAttributesType>\n  > {\n    // Validate codeVerifier is not an empty string (common mistake)\n    if (codeVerifier !== undefined && codeVerifier.trim() === '') {\n      throw new TypeError(\n        'codeVerifier cannot be an empty string. ' +\n          'Generate a valid PKCE pair using workos.pkce.generate().',\n      );\n    }\n\n    const hasApiKey = !!this.workos.key;\n    const hasPKCE = !!codeVerifier;\n\n    if (!hasPKCE && !hasApiKey) {\n      throw new TypeError(\n        'getProfileAndToken requires either a codeVerifier (for public clients) ' +\n          'or an API key configured on the WorkOS instance (for confidential clients).',\n      );\n    }\n\n    const form = new URLSearchParams({\n      client_id: clientId,\n      grant_type: 'authorization_code',\n      code,\n    });\n\n    // Support PKCE with confidential clients (OAuth 2.1 best practice)\n    // Both can be sent together for defense in depth\n    if (hasPKCE) {\n      form.set('code_verifier', codeVerifier);\n    }\n    if (hasApiKey) {\n      form.set('client_secret', this.workos.key as string);\n    }\n\n    const { data } = await this.workos.post<\n      ProfileAndTokenResponse<CustomAttributesType>\n    >('/sso/token', form, { skipApiKeyCheck: !hasApiKey });\n\n    return deserializeProfileAndToken(data);\n  }\n\n  async getProfile<CustomAttributesType extends UnknownRecord = UnknownRecord>({\n    accessToken,\n  }: GetProfileOptions): Promise<Profile<CustomAttributesType>> {\n    const { data } = await this.workos.get<\n      ProfileResponse<CustomAttributesType>\n    >('/sso/profile', {\n      accessToken,\n    });\n\n    return deserializeProfile(data);\n  }\n}\n"],"mappings":";;;;;;;;;AA0BA,IAAa,MAAb,MAAiB;CACf,YAAY,AAAiBA,QAAgB;EAAhB;;CAE7B,MAAM,gBACJ,SACwE;AACxE,SAAO,IAAIC,gDACT,MAAMC,+DACJ,KAAK,QACL,gBACAC,qEACA,UAAUC,4FAAgC,QAAQ,GAAG,OACtD,GACA,WACCF,+DACE,KAAK,QACL,gBACAC,qEACA,OACD,EACH,UAAUC,4FAAgC,QAAQ,GAAG,OACtD;;CAEH,MAAM,iBAAiB,IAAY;AACjC,QAAM,KAAK,OAAO,OAAO,gBAAgB,KAAK;;CAGhD,oBAAoB,SAA6C;EAC/D,MAAM,EACJ,eACA,qBACA,YACA,UACA,YACA,WACA,cACA,UACA,qBACA,gBACA,aACA,UACE;AAEJ,MAAI,CAAC,YAAY,CAAC,cAAc,CAAC,aAC/B,OAAM,IAAI,UACR,8FACD;EAGH,MAAM,QAAQC,gDAAc;GAC1B,gBAAgB;GAChB,uBAAuB;GACvB;GACA;GACA,aAAa;GACb,YAAY;GACZ;GACA,uBAAuB;GACvB,iBAAiB;GACjB,WAAW;GACX,cAAc;GACd,eAAe;GACf;GACD,CAAC;AAEF,SAAO,GAAG,KAAK,OAAO,QAAQ,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BjD,MAAM,4BACJ,SAIwC;EACxC,MAAM,EACJ,YACA,UACA,YACA,WACA,cACA,UACA,qBACA,gBACA,gBACE;AAEJ,MAAI,CAAC,YAAY,CAAC,cAAc,CAAC,aAC/B,OAAM,IAAI,UACR,8FACD;EAIH,MAAM,OAAO,MAAM,KAAK,OAAO,KAAK,UAAU;EAG9C,MAAM,QAAQ,KAAK,OAAO,KAAK,qBAAqB,GAAG;EAEvD,MAAM,QAAQA,gDAAc;GAC1B,gBAAgB,KAAK;GACrB,uBAAuB;GACvB;GACA;GACA,aAAa;GACb,YAAY;GACZ;GACA,uBAAuB;GACvB,iBAAiB;GACjB,WAAW;GACX,cAAc;GACd,eAAe;GACf;GACD,CAAC;AAIF,SAAO;GAAE,KAFG,GAAG,KAAK,OAAO,QAAQ,iBAAiB;GAEtC;GAAO,cAAc,KAAK;GAAc;;CAGxD,MAAM,cAAc,IAAiC;EACnD,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,IACjC,gBAAgB,KACjB;AAED,SAAOF,oEAAsB,KAAK;;;;;;;;;;;;;;;CAgBpC,MAAM,mBAEJ,EACA,MACA,UACA,gBAGA;AAEA,MAAI,iBAAiB,UAAa,aAAa,MAAM,KAAK,GACxD,OAAM,IAAI,UACR,mGAED;EAGH,MAAM,YAAY,CAAC,CAAC,KAAK,OAAO;EAChC,MAAM,UAAU,CAAC,CAAC;AAElB,MAAI,CAAC,WAAW,CAAC,UACf,OAAM,IAAI,UACR,qJAED;EAGH,MAAM,OAAO,IAAI,gBAAgB;GAC/B,WAAW;GACX,YAAY;GACZ;GACD,CAAC;AAIF,MAAI,QACF,MAAK,IAAI,iBAAiB,aAAa;AAEzC,MAAI,UACF,MAAK,IAAI,iBAAiB,KAAK,OAAO,IAAc;EAGtD,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,KAEjC,cAAc,MAAM,EAAE,iBAAiB,CAAC,WAAW,CAAC;AAEtD,SAAOG,gFAA2B,KAAK;;CAGzC,MAAM,WAAuE,EAC3E,eAC4D;EAC5D,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,IAEjC,gBAAgB,EAChB,aACD,CAAC;AAEF,SAAOC,8DAAmB,KAAK"}

package/lib/sso/sso.d.cts

@@ -1,4 +1,4 @@
-import { SSOAuthorizationURLOptions } from "./interfaces/authorization-url-options.interface.cjs";
+import { SSOAuthorizationURLOptions, SSOPKCEAuthorizationURLResult } from "./interfaces/authorization-url-options.interface.cjs";
 import { Connection } from "./interfaces/connection.interface.cjs";
 import { GetProfileOptions } from "./interfaces/get-profile-options.interface.cjs";
 import { GetProfileAndTokenOptions } from "./interfaces/get-profile-and-token-options.interface.cjs";
@@ -16,10 +16,49 @@ declare class SSO {
   listConnections(options?: ListConnectionsOptions): Promise<AutoPaginatable<Connection, SerializedListConnectionsOptions>>;
   deleteConnection(id: string): Promise<void>;
   getAuthorizationUrl(options: SSOAuthorizationURLOptions): string;
+  /**
+   * Generates an authorization URL with PKCE parameters automatically generated.
+   * Use this for public clients (CLI apps, Electron, mobile) that cannot
+   * securely store a client secret.
+   *
+   * @returns Object containing url, state, and codeVerifier
+   *
+   * @example
+   * ```typescript
+   * const { url, state, codeVerifier } = await workos.sso.getAuthorizationUrlWithPKCE({
+   *   connection: 'conn_123',
+   *   clientId: 'client_123',
+   *   redirectUri: 'myapp://callback',
+   * });
+   *
+   * // Store state and codeVerifier securely, then redirect user to url
+   * // After callback, exchange the code:
+   * const { profile, accessToken } = await workos.sso.getProfileAndToken({
+   *   code: authorizationCode,
+   *   codeVerifier,
+   *   clientId: 'client_123',
+   * });
+   * ```
+   */
+  getAuthorizationUrlWithPKCE(options: Omit<SSOAuthorizationURLOptions, 'codeChallenge' | 'codeChallengeMethod' | 'state'>): Promise<SSOPKCEAuthorizationURLResult>;
   getConnection(id: string): Promise<Connection>;
+  /**
+   * Exchange an authorization code for a profile and access token.
+   *
+   * Auto-detects public vs confidential client mode:
+   * - If codeVerifier is provided: Uses PKCE flow (public client)
+   * - If no codeVerifier: Uses client_secret from API key (confidential client)
+   * - If both: Uses both client_secret AND codeVerifier (confidential client with PKCE)
+   *
+   * Using PKCE with confidential clients is recommended by OAuth 2.1 for defense
+   * in depth and provides additional CSRF protection on the authorization flow.
+   *
+   * @throws Error if neither codeVerifier nor API key is available
+   */
   getProfileAndToken<CustomAttributesType extends UnknownRecord = UnknownRecord>({
     code,
-    clientId
+    clientId,
+    codeVerifier
   }: GetProfileAndTokenOptions): Promise<ProfileAndToken<CustomAttributesType>>;
   getProfile<CustomAttributesType extends UnknownRecord = UnknownRecord>({
     accessToken

package/lib/sso/sso.d.ts

@@ -1,4 +1,4 @@
-import { SSOAuthorizationURLOptions } from "./interfaces/authorization-url-options.interface.js";
+import { SSOAuthorizationURLOptions, SSOPKCEAuthorizationURLResult } from "./interfaces/authorization-url-options.interface.js";
 import { Connection } from "./interfaces/connection.interface.js";
 import { GetProfileOptions } from "./interfaces/get-profile-options.interface.js";
 import { GetProfileAndTokenOptions } from "./interfaces/get-profile-and-token-options.interface.js";
@@ -16,10 +16,49 @@ declare class SSO {
   listConnections(options?: ListConnectionsOptions): Promise<AutoPaginatable<Connection, SerializedListConnectionsOptions>>;
   deleteConnection(id: string): Promise<void>;
   getAuthorizationUrl(options: SSOAuthorizationURLOptions): string;
+  /**
+   * Generates an authorization URL with PKCE parameters automatically generated.
+   * Use this for public clients (CLI apps, Electron, mobile) that cannot
+   * securely store a client secret.
+   *
+   * @returns Object containing url, state, and codeVerifier
+   *
+   * @example
+   * ```typescript
+   * const { url, state, codeVerifier } = await workos.sso.getAuthorizationUrlWithPKCE({
+   *   connection: 'conn_123',
+   *   clientId: 'client_123',
+   *   redirectUri: 'myapp://callback',
+   * });
+   *
+   * // Store state and codeVerifier securely, then redirect user to url
+   * // After callback, exchange the code:
+   * const { profile, accessToken } = await workos.sso.getProfileAndToken({
+   *   code: authorizationCode,
+   *   codeVerifier,
+   *   clientId: 'client_123',
+   * });
+   * ```
+   */
+  getAuthorizationUrlWithPKCE(options: Omit<SSOAuthorizationURLOptions, 'codeChallenge' | 'codeChallengeMethod' | 'state'>): Promise<SSOPKCEAuthorizationURLResult>;
   getConnection(id: string): Promise<Connection>;
+  /**
+   * Exchange an authorization code for a profile and access token.
+   *
+   * Auto-detects public vs confidential client mode:
+   * - If codeVerifier is provided: Uses PKCE flow (public client)
+   * - If no codeVerifier: Uses client_secret from API key (confidential client)
+   * - If both: Uses both client_secret AND codeVerifier (confidential client with PKCE)
+   *
+   * Using PKCE with confidential clients is recommended by OAuth 2.1 for defense
+   * in depth and provides additional CSRF protection on the authorization flow.
+   *
+   * @throws Error if neither codeVerifier nor API key is available
+   */
   getProfileAndToken<CustomAttributesType extends UnknownRecord = UnknownRecord>({
     code,
-    clientId
+    clientId,
+    codeVerifier
   }: GetProfileAndTokenOptions): Promise<ProfileAndToken<CustomAttributesType>>;
   getProfile<CustomAttributesType extends UnknownRecord = UnknownRecord>({
     accessToken

package/lib/sso/sso.js

@@ -1,10 +1,10 @@
-import { getAuthorizationUrl } from "../client/sso.js";
+import { AutoPaginatable } from "../common/utils/pagination.js";
 import { deserializeConnection } from "./serializers/connection.serializer.js";
 import { serializeListConnectionsOptions } from "./serializers/list-connections-options.serializer.js";
 import { deserializeProfile } from "./serializers/profile.serializer.js";
 import { deserializeProfileAndToken } from "./serializers/profile-and-token.serializer.js";
-import { AutoPaginatable } from "../common/utils/pagination.js";
 import { fetchAndDeserialize } from "../common/utils/fetch-and-deserialize.js";
+import { toQueryString } from "../common/utils/query-string.js";
 
 //#region src/sso/sso.ts
 var SSO = class {
@@ -18,23 +18,105 @@ var SSO = class {
 		await this.workos.delete(`/connections/${id}`);
 	}
 	getAuthorizationUrl(options) {
-		return getAuthorizationUrl({
-			...options,
-			baseURL: this.workos.baseURL
+		const { codeChallenge, codeChallengeMethod, connection, clientId, domainHint, loginHint, organization, provider, providerQueryParams, providerScopes, redirectUri, state } = options;
+		if (!provider && !connection && !organization) throw new TypeError(`Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`);
+		const query = toQueryString({
+			code_challenge: codeChallenge,
+			code_challenge_method: codeChallengeMethod,
+			connection,
+			organization,
+			domain_hint: domainHint,
+			login_hint: loginHint,
+			provider,
+			provider_query_params: providerQueryParams,
+			provider_scopes: providerScopes,
+			client_id: clientId,
+			redirect_uri: redirectUri,
+			response_type: "code",
+			state
+		});
+		return `${this.workos.baseURL}/sso/authorize?${query}`;
+	}
+	/**
+	* Generates an authorization URL with PKCE parameters automatically generated.
+	* Use this for public clients (CLI apps, Electron, mobile) that cannot
+	* securely store a client secret.
+	*
+	* @returns Object containing url, state, and codeVerifier
+	*
+	* @example
+	* ```typescript
+	* const { url, state, codeVerifier } = await workos.sso.getAuthorizationUrlWithPKCE({
+	*   connection: 'conn_123',
+	*   clientId: 'client_123',
+	*   redirectUri: 'myapp://callback',
+	* });
+	*
+	* // Store state and codeVerifier securely, then redirect user to url
+	* // After callback, exchange the code:
+	* const { profile, accessToken } = await workos.sso.getProfileAndToken({
+	*   code: authorizationCode,
+	*   codeVerifier,
+	*   clientId: 'client_123',
+	* });
+	* ```
+	*/
+	async getAuthorizationUrlWithPKCE(options) {
+		const { connection, clientId, domainHint, loginHint, organization, provider, providerQueryParams, providerScopes, redirectUri } = options;
+		if (!provider && !connection && !organization) throw new TypeError(`Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`);
+		const pkce = await this.workos.pkce.generate();
+		const state = this.workos.pkce.generateCodeVerifier(43);
+		const query = toQueryString({
+			code_challenge: pkce.codeChallenge,
+			code_challenge_method: "S256",
+			connection,
+			organization,
+			domain_hint: domainHint,
+			login_hint: loginHint,
+			provider,
+			provider_query_params: providerQueryParams,
+			provider_scopes: providerScopes,
+			client_id: clientId,
+			redirect_uri: redirectUri,
+			response_type: "code",
+			state
 		});
+		return {
+			url: `${this.workos.baseURL}/sso/authorize?${query}`,
+			state,
+			codeVerifier: pkce.codeVerifier
+		};
 	}
 	async getConnection(id) {
 		const { data } = await this.workos.get(`/connections/${id}`);
 		return deserializeConnection(data);
 	}
-	async getProfileAndToken({ code, clientId }) {
+	/**
+	* Exchange an authorization code for a profile and access token.
+	*
+	* Auto-detects public vs confidential client mode:
+	* - If codeVerifier is provided: Uses PKCE flow (public client)
+	* - If no codeVerifier: Uses client_secret from API key (confidential client)
+	* - If both: Uses both client_secret AND codeVerifier (confidential client with PKCE)
+	*
+	* Using PKCE with confidential clients is recommended by OAuth 2.1 for defense
+	* in depth and provides additional CSRF protection on the authorization flow.
+	*
+	* @throws Error if neither codeVerifier nor API key is available
+	*/
+	async getProfileAndToken({ code, clientId, codeVerifier }) {
+		if (codeVerifier !== void 0 && codeVerifier.trim() === "") throw new TypeError("codeVerifier cannot be an empty string. Generate a valid PKCE pair using workos.pkce.generate().");
+		const hasApiKey = !!this.workos.key;
+		const hasPKCE = !!codeVerifier;
+		if (!hasPKCE && !hasApiKey) throw new TypeError("getProfileAndToken requires either a codeVerifier (for public clients) or an API key configured on the WorkOS instance (for confidential clients).");
 		const form = new URLSearchParams({
 			client_id: clientId,
-			client_secret: this.workos.key,
 			grant_type: "authorization_code",
 			code
 		});
-		const { data } = await this.workos.post("/sso/token", form);
+		if (hasPKCE) form.set("code_verifier", codeVerifier);
+		if (hasApiKey) form.set("client_secret", this.workos.key);
+		const { data } = await this.workos.post("/sso/token", form, { skipApiKeyCheck: !hasApiKey });
 		return deserializeProfileAndToken(data);
 	}
 	async getProfile({ accessToken }) {

package/lib/sso/sso.js.map

@@ -1 +1 @@
-{"version":3,"file":"sso.js","names":["workos: WorkOS","clientSSO.getAuthorizationUrl"],"sources":["../../src/sso/sso.ts"],"sourcesContent":["import * as clientSSO from '../client/sso';\nimport { UnknownRecord } from '../common/interfaces/unknown-record.interface';\nimport { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';\nimport { AutoPaginatable } from '../common/utils/pagination';\nimport { WorkOS } from '../workos';\nimport {\n  Connection,\n  ConnectionResponse,\n  GetProfileAndTokenOptions,\n  GetProfileOptions,\n  ListConnectionsOptions,\n  Profile,\n  ProfileAndToken,\n  ProfileAndTokenResponse,\n  ProfileResponse,\n  SSOAuthorizationURLOptions,\n  SerializedListConnectionsOptions,\n} from './interfaces';\nimport {\n  deserializeConnection,\n  deserializeProfile,\n  deserializeProfileAndToken,\n  serializeListConnectionsOptions,\n} from './serializers';\n\nexport class SSO {\n  constructor(private readonly workos: WorkOS) {}\n\n  async listConnections(\n    options?: ListConnectionsOptions,\n  ): Promise<AutoPaginatable<Connection, SerializedListConnectionsOptions>> {\n    return new AutoPaginatable(\n      await fetchAndDeserialize<ConnectionResponse, Connection>(\n        this.workos,\n        '/connections',\n        deserializeConnection,\n        options ? serializeListConnectionsOptions(options) : undefined,\n      ),\n      (params) =>\n        fetchAndDeserialize<ConnectionResponse, Connection>(\n          this.workos,\n          '/connections',\n          deserializeConnection,\n          params,\n        ),\n      options ? serializeListConnectionsOptions(options) : undefined,\n    );\n  }\n  async deleteConnection(id: string) {\n    await this.workos.delete(`/connections/${id}`);\n  }\n\n  getAuthorizationUrl(options: SSOAuthorizationURLOptions): string {\n    // Delegate to client implementation\n    return clientSSO.getAuthorizationUrl({\n      ...options,\n      baseURL: this.workos.baseURL,\n    });\n  }\n\n  async getConnection(id: string): Promise<Connection> {\n    const { data } = await this.workos.get<ConnectionResponse>(\n      `/connections/${id}`,\n    );\n\n    return deserializeConnection(data);\n  }\n\n  async getProfileAndToken<\n    CustomAttributesType extends UnknownRecord = UnknownRecord,\n  >({\n    code,\n    clientId,\n  }: GetProfileAndTokenOptions): Promise<\n    ProfileAndToken<CustomAttributesType>\n  > {\n    const form = new URLSearchParams({\n      client_id: clientId,\n      client_secret: this.workos.key as string,\n      grant_type: 'authorization_code',\n      code,\n    });\n\n    const { data } = await this.workos.post<\n      ProfileAndTokenResponse<CustomAttributesType>\n    >('/sso/token', form);\n\n    return deserializeProfileAndToken(data);\n  }\n\n  async getProfile<CustomAttributesType extends UnknownRecord = UnknownRecord>({\n    accessToken,\n  }: GetProfileOptions): Promise<Profile<CustomAttributesType>> {\n    const { data } = await this.workos.get<\n      ProfileResponse<CustomAttributesType>\n    >('/sso/profile', {\n      accessToken,\n    });\n\n    return deserializeProfile(data);\n  }\n}\n"],"mappings":";;;;;;;;;AAyBA,IAAa,MAAb,MAAiB;CACf,YAAY,AAAiBA,QAAgB;EAAhB;;CAE7B,MAAM,gBACJ,SACwE;AACxE,SAAO,IAAI,gBACT,MAAM,oBACJ,KAAK,QACL,gBACA,uBACA,UAAU,gCAAgC,QAAQ,GAAG,OACtD,GACA,WACC,oBACE,KAAK,QACL,gBACA,uBACA,OACD,EACH,UAAU,gCAAgC,QAAQ,GAAG,OACtD;;CAEH,MAAM,iBAAiB,IAAY;AACjC,QAAM,KAAK,OAAO,OAAO,gBAAgB,KAAK;;CAGhD,oBAAoB,SAA6C;AAE/D,SAAOC,oBAA8B;GACnC,GAAG;GACH,SAAS,KAAK,OAAO;GACtB,CAAC;;CAGJ,MAAM,cAAc,IAAiC;EACnD,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,IACjC,gBAAgB,KACjB;AAED,SAAO,sBAAsB,KAAK;;CAGpC,MAAM,mBAEJ,EACA,MACA,YAGA;EACA,MAAM,OAAO,IAAI,gBAAgB;GAC/B,WAAW;GACX,eAAe,KAAK,OAAO;GAC3B,YAAY;GACZ;GACD,CAAC;EAEF,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,KAEjC,cAAc,KAAK;AAErB,SAAO,2BAA2B,KAAK;;CAGzC,MAAM,WAAuE,EAC3E,eAC4D;EAC5D,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,IAEjC,gBAAgB,EAChB,aACD,CAAC;AAEF,SAAO,mBAAmB,KAAK"}
+{"version":3,"file":"sso.js","names":["workos: WorkOS"],"sources":["../../src/sso/sso.ts"],"sourcesContent":["import { UnknownRecord } from '../common/interfaces/unknown-record.interface';\nimport { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';\nimport { AutoPaginatable } from '../common/utils/pagination';\nimport { toQueryString } from '../common/utils/query-string';\nimport { WorkOS } from '../workos';\nimport {\n  Connection,\n  ConnectionResponse,\n  GetProfileAndTokenOptions,\n  GetProfileOptions,\n  ListConnectionsOptions,\n  Profile,\n  ProfileAndToken,\n  ProfileAndTokenResponse,\n  ProfileResponse,\n  SSOAuthorizationURLOptions,\n  SSOPKCEAuthorizationURLResult,\n  SerializedListConnectionsOptions,\n} from './interfaces';\nimport {\n  deserializeConnection,\n  deserializeProfile,\n  deserializeProfileAndToken,\n  serializeListConnectionsOptions,\n} from './serializers';\n\nexport class SSO {\n  constructor(private readonly workos: WorkOS) {}\n\n  async listConnections(\n    options?: ListConnectionsOptions,\n  ): Promise<AutoPaginatable<Connection, SerializedListConnectionsOptions>> {\n    return new AutoPaginatable(\n      await fetchAndDeserialize<ConnectionResponse, Connection>(\n        this.workos,\n        '/connections',\n        deserializeConnection,\n        options ? serializeListConnectionsOptions(options) : undefined,\n      ),\n      (params) =>\n        fetchAndDeserialize<ConnectionResponse, Connection>(\n          this.workos,\n          '/connections',\n          deserializeConnection,\n          params,\n        ),\n      options ? serializeListConnectionsOptions(options) : undefined,\n    );\n  }\n  async deleteConnection(id: string) {\n    await this.workos.delete(`/connections/${id}`);\n  }\n\n  getAuthorizationUrl(options: SSOAuthorizationURLOptions): string {\n    const {\n      codeChallenge,\n      codeChallengeMethod,\n      connection,\n      clientId,\n      domainHint,\n      loginHint,\n      organization,\n      provider,\n      providerQueryParams,\n      providerScopes,\n      redirectUri,\n      state,\n    } = options;\n\n    if (!provider && !connection && !organization) {\n      throw new TypeError(\n        `Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`,\n      );\n    }\n\n    const query = toQueryString({\n      code_challenge: codeChallenge,\n      code_challenge_method: codeChallengeMethod,\n      connection,\n      organization,\n      domain_hint: domainHint,\n      login_hint: loginHint,\n      provider,\n      provider_query_params: providerQueryParams,\n      provider_scopes: providerScopes,\n      client_id: clientId,\n      redirect_uri: redirectUri,\n      response_type: 'code',\n      state,\n    });\n\n    return `${this.workos.baseURL}/sso/authorize?${query}`;\n  }\n\n  /**\n   * Generates an authorization URL with PKCE parameters automatically generated.\n   * Use this for public clients (CLI apps, Electron, mobile) that cannot\n   * securely store a client secret.\n   *\n   * @returns Object containing url, state, and codeVerifier\n   *\n   * @example\n   * ```typescript\n   * const { url, state, codeVerifier } = await workos.sso.getAuthorizationUrlWithPKCE({\n   *   connection: 'conn_123',\n   *   clientId: 'client_123',\n   *   redirectUri: 'myapp://callback',\n   * });\n   *\n   * // Store state and codeVerifier securely, then redirect user to url\n   * // After callback, exchange the code:\n   * const { profile, accessToken } = await workos.sso.getProfileAndToken({\n   *   code: authorizationCode,\n   *   codeVerifier,\n   *   clientId: 'client_123',\n   * });\n   * ```\n   */\n  async getAuthorizationUrlWithPKCE(\n    options: Omit<\n      SSOAuthorizationURLOptions,\n      'codeChallenge' | 'codeChallengeMethod' | 'state'\n    >,\n  ): Promise<SSOPKCEAuthorizationURLResult> {\n    const {\n      connection,\n      clientId,\n      domainHint,\n      loginHint,\n      organization,\n      provider,\n      providerQueryParams,\n      providerScopes,\n      redirectUri,\n    } = options;\n\n    if (!provider && !connection && !organization) {\n      throw new TypeError(\n        `Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`,\n      );\n    }\n\n    // Generate PKCE parameters\n    const pkce = await this.workos.pkce.generate();\n\n    // Generate secure random state\n    const state = this.workos.pkce.generateCodeVerifier(43);\n\n    const query = toQueryString({\n      code_challenge: pkce.codeChallenge,\n      code_challenge_method: 'S256',\n      connection,\n      organization,\n      domain_hint: domainHint,\n      login_hint: loginHint,\n      provider,\n      provider_query_params: providerQueryParams,\n      provider_scopes: providerScopes,\n      client_id: clientId,\n      redirect_uri: redirectUri,\n      response_type: 'code',\n      state,\n    });\n\n    const url = `${this.workos.baseURL}/sso/authorize?${query}`;\n\n    return { url, state, codeVerifier: pkce.codeVerifier };\n  }\n\n  async getConnection(id: string): Promise<Connection> {\n    const { data } = await this.workos.get<ConnectionResponse>(\n      `/connections/${id}`,\n    );\n\n    return deserializeConnection(data);\n  }\n\n  /**\n   * Exchange an authorization code for a profile and access token.\n   *\n   * Auto-detects public vs confidential client mode:\n   * - If codeVerifier is provided: Uses PKCE flow (public client)\n   * - If no codeVerifier: Uses client_secret from API key (confidential client)\n   * - If both: Uses both client_secret AND codeVerifier (confidential client with PKCE)\n   *\n   * Using PKCE with confidential clients is recommended by OAuth 2.1 for defense\n   * in depth and provides additional CSRF protection on the authorization flow.\n   *\n   * @throws Error if neither codeVerifier nor API key is available\n   */\n  async getProfileAndToken<\n    CustomAttributesType extends UnknownRecord = UnknownRecord,\n  >({\n    code,\n    clientId,\n    codeVerifier,\n  }: GetProfileAndTokenOptions): Promise<\n    ProfileAndToken<CustomAttributesType>\n  > {\n    // Validate codeVerifier is not an empty string (common mistake)\n    if (codeVerifier !== undefined && codeVerifier.trim() === '') {\n      throw new TypeError(\n        'codeVerifier cannot be an empty string. ' +\n          'Generate a valid PKCE pair using workos.pkce.generate().',\n      );\n    }\n\n    const hasApiKey = !!this.workos.key;\n    const hasPKCE = !!codeVerifier;\n\n    if (!hasPKCE && !hasApiKey) {\n      throw new TypeError(\n        'getProfileAndToken requires either a codeVerifier (for public clients) ' +\n          'or an API key configured on the WorkOS instance (for confidential clients).',\n      );\n    }\n\n    const form = new URLSearchParams({\n      client_id: clientId,\n      grant_type: 'authorization_code',\n      code,\n    });\n\n    // Support PKCE with confidential clients (OAuth 2.1 best practice)\n    // Both can be sent together for defense in depth\n    if (hasPKCE) {\n      form.set('code_verifier', codeVerifier);\n    }\n    if (hasApiKey) {\n      form.set('client_secret', this.workos.key as string);\n    }\n\n    const { data } = await this.workos.post<\n      ProfileAndTokenResponse<CustomAttributesType>\n    >('/sso/token', form, { skipApiKeyCheck: !hasApiKey });\n\n    return deserializeProfileAndToken(data);\n  }\n\n  async getProfile<CustomAttributesType extends UnknownRecord = UnknownRecord>({\n    accessToken,\n  }: GetProfileOptions): Promise<Profile<CustomAttributesType>> {\n    const { data } = await this.workos.get<\n      ProfileResponse<CustomAttributesType>\n    >('/sso/profile', {\n      accessToken,\n    });\n\n    return deserializeProfile(data);\n  }\n}\n"],"mappings":";;;;;;;;;AA0BA,IAAa,MAAb,MAAiB;CACf,YAAY,AAAiBA,QAAgB;EAAhB;;CAE7B,MAAM,gBACJ,SACwE;AACxE,SAAO,IAAI,gBACT,MAAM,oBACJ,KAAK,QACL,gBACA,uBACA,UAAU,gCAAgC,QAAQ,GAAG,OACtD,GACA,WACC,oBACE,KAAK,QACL,gBACA,uBACA,OACD,EACH,UAAU,gCAAgC,QAAQ,GAAG,OACtD;;CAEH,MAAM,iBAAiB,IAAY;AACjC,QAAM,KAAK,OAAO,OAAO,gBAAgB,KAAK;;CAGhD,oBAAoB,SAA6C;EAC/D,MAAM,EACJ,eACA,qBACA,YACA,UACA,YACA,WACA,cACA,UACA,qBACA,gBACA,aACA,UACE;AAEJ,MAAI,CAAC,YAAY,CAAC,cAAc,CAAC,aAC/B,OAAM,IAAI,UACR,8FACD;EAGH,MAAM,QAAQ,cAAc;GAC1B,gBAAgB;GAChB,uBAAuB;GACvB;GACA;GACA,aAAa;GACb,YAAY;GACZ;GACA,uBAAuB;GACvB,iBAAiB;GACjB,WAAW;GACX,cAAc;GACd,eAAe;GACf;GACD,CAAC;AAEF,SAAO,GAAG,KAAK,OAAO,QAAQ,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BjD,MAAM,4BACJ,SAIwC;EACxC,MAAM,EACJ,YACA,UACA,YACA,WACA,cACA,UACA,qBACA,gBACA,gBACE;AAEJ,MAAI,CAAC,YAAY,CAAC,cAAc,CAAC,aAC/B,OAAM,IAAI,UACR,8FACD;EAIH,MAAM,OAAO,MAAM,KAAK,OAAO,KAAK,UAAU;EAG9C,MAAM,QAAQ,KAAK,OAAO,KAAK,qBAAqB,GAAG;EAEvD,MAAM,QAAQ,cAAc;GAC1B,gBAAgB,KAAK;GACrB,uBAAuB;GACvB;GACA;GACA,aAAa;GACb,YAAY;GACZ;GACA,uBAAuB;GACvB,iBAAiB;GACjB,WAAW;GACX,cAAc;GACd,eAAe;GACf;GACD,CAAC;AAIF,SAAO;GAAE,KAFG,GAAG,KAAK,OAAO,QAAQ,iBAAiB;GAEtC;GAAO,cAAc,KAAK;GAAc;;CAGxD,MAAM,cAAc,IAAiC;EACnD,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,IACjC,gBAAgB,KACjB;AAED,SAAO,sBAAsB,KAAK;;;;;;;;;;;;;;;CAgBpC,MAAM,mBAEJ,EACA,MACA,UACA,gBAGA;AAEA,MAAI,iBAAiB,UAAa,aAAa,MAAM,KAAK,GACxD,OAAM,IAAI,UACR,mGAED;EAGH,MAAM,YAAY,CAAC,CAAC,KAAK,OAAO;EAChC,MAAM,UAAU,CAAC,CAAC;AAElB,MAAI,CAAC,WAAW,CAAC,UACf,OAAM,IAAI,UACR,qJAED;EAGH,MAAM,OAAO,IAAI,gBAAgB;GAC/B,WAAW;GACX,YAAY;GACZ;GACD,CAAC;AAIF,MAAI,QACF,MAAK,IAAI,iBAAiB,aAAa;AAEzC,MAAI,UACF,MAAK,IAAI,iBAAiB,KAAK,OAAO,IAAc;EAGtD,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,KAEjC,cAAc,MAAM,EAAE,iBAAiB,CAAC,WAAW,CAAC;AAEtD,SAAO,2BAA2B,KAAK;;CAGzC,MAAM,WAAuE,EAC3E,eAC4D;EAC5D,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,IAEjC,gBAAgB,EAChB,aACD,CAAC;AAEF,SAAO,mBAAmB,KAAK"}

package/lib/user-management/interfaces/authenticate-with-code-and-verifier-options.interface.d.cts

@@ -1,4 +1,4 @@
-import { AuthenticateWithOptionsBase, SerializedAuthenticateWithPKCEBase } from "./authenticate-with-options-base.interface.cjs";
+import { AuthenticateWithOptionsBase, SerializedAuthenticatePublicClientBase } from "./authenticate-with-options-base.interface.cjs";
 
 //#region src/user-management/interfaces/authenticate-with-code-and-verifier-options.interface.d.ts
 interface AuthenticateWithCodeAndVerifierOptions extends AuthenticateWithOptionsBase {
@@ -6,7 +6,7 @@ interface AuthenticateWithCodeAndVerifierOptions extends AuthenticateWithOptions
   code: string;
   invitationToken?: string;
 }
-interface SerializedAuthenticateWithCodeAndVerifierOptions extends SerializedAuthenticateWithPKCEBase {
+interface SerializedAuthenticateWithCodeAndVerifierOptions extends SerializedAuthenticatePublicClientBase {
   grant_type: 'authorization_code';
   code_verifier: string;
   code: string;

package/lib/user-management/interfaces/authenticate-with-code-and-verifier-options.interface.d.ts

@@ -1,4 +1,4 @@
-import { AuthenticateWithOptionsBase, SerializedAuthenticateWithPKCEBase } from "./authenticate-with-options-base.interface.js";
+import { AuthenticateWithOptionsBase, SerializedAuthenticatePublicClientBase } from "./authenticate-with-options-base.interface.js";
 
 //#region src/user-management/interfaces/authenticate-with-code-and-verifier-options.interface.d.ts
 interface AuthenticateWithCodeAndVerifierOptions extends AuthenticateWithOptionsBase {
@@ -6,7 +6,7 @@ interface AuthenticateWithCodeAndVerifierOptions extends AuthenticateWithOptions
   code: string;
   invitationToken?: string;
 }
-interface SerializedAuthenticateWithCodeAndVerifierOptions extends SerializedAuthenticateWithPKCEBase {
+interface SerializedAuthenticateWithCodeAndVerifierOptions extends SerializedAuthenticatePublicClientBase {
   grant_type: 'authorization_code';
   code_verifier: string;
   code: string;

package/lib/user-management/interfaces/authenticate-with-options-base.interface.d.cts

@@ -4,7 +4,7 @@ interface AuthenticateWithSessionOptions {
   sealSession: boolean;
 }
 interface AuthenticateWithOptionsBase {
-  clientId: string;
+  clientId?: string;
   ipAddress?: string;
   userAgent?: string;
   session?: AuthenticateWithSessionOptions;
@@ -15,11 +15,27 @@ interface SerializedAuthenticateWithOptionsBase {
   ip_address?: string;
   user_agent?: string;
 }
-interface SerializedAuthenticateWithPKCEBase {
+/** Base for serialized auth options that don't require client_secret (public clients) */
+interface SerializedAuthenticatePublicClientBase {
   client_id: string;
   ip_address?: string;
   user_agent?: string;
 }
+/**
+ * Utility type for serializer input signatures.
+ *
+ * Since `clientId` is optional in user-facing interfaces (allowing fallback to
+ * the constructor-provided value), but serializers require a resolved string,
+ * this type overrides the optional `clientId` with a required one.
+ *
+ * Usage in serializers:
+ * ```
+ * const serialize = (options: WithResolvedClientId<SomeOptions>) => ...
+ * ```
+ */
+type WithResolvedClientId<T> = Omit<T, 'clientId'> & {
+  clientId: string;
+};
 //#endregion
-export { AuthenticateWithOptionsBase, AuthenticateWithSessionOptions, SerializedAuthenticateWithOptionsBase, SerializedAuthenticateWithPKCEBase };
+export { AuthenticateWithOptionsBase, AuthenticateWithSessionOptions, SerializedAuthenticatePublicClientBase, SerializedAuthenticateWithOptionsBase, WithResolvedClientId };
 //# sourceMappingURL=authenticate-with-options-base.interface.d.cts.map

package/lib/user-management/interfaces/authenticate-with-options-base.interface.d.ts

@@ -4,7 +4,7 @@ interface AuthenticateWithSessionOptions {
   sealSession: boolean;
 }
 interface AuthenticateWithOptionsBase {
-  clientId: string;
+  clientId?: string;
   ipAddress?: string;
   userAgent?: string;
   session?: AuthenticateWithSessionOptions;
@@ -15,11 +15,27 @@ interface SerializedAuthenticateWithOptionsBase {
   ip_address?: string;
   user_agent?: string;
 }
-interface SerializedAuthenticateWithPKCEBase {
+/** Base for serialized auth options that don't require client_secret (public clients) */
+interface SerializedAuthenticatePublicClientBase {
   client_id: string;
   ip_address?: string;
   user_agent?: string;
 }
+/**
+ * Utility type for serializer input signatures.
+ *
+ * Since `clientId` is optional in user-facing interfaces (allowing fallback to
+ * the constructor-provided value), but serializers require a resolved string,
+ * this type overrides the optional `clientId` with a required one.
+ *
+ * Usage in serializers:
+ * ```
+ * const serialize = (options: WithResolvedClientId<SomeOptions>) => ...
+ * ```
+ */
+type WithResolvedClientId<T> = Omit<T, 'clientId'> & {
+  clientId: string;
+};
 //#endregion
-export { AuthenticateWithOptionsBase, AuthenticateWithSessionOptions, SerializedAuthenticateWithOptionsBase, SerializedAuthenticateWithPKCEBase };
+export { AuthenticateWithOptionsBase, AuthenticateWithSessionOptions, SerializedAuthenticatePublicClientBase, SerializedAuthenticateWithOptionsBase, WithResolvedClientId };
 //# sourceMappingURL=authenticate-with-options-base.interface.d.ts.map

package/lib/user-management/interfaces/authenticate-with-refresh-token-public-client-options.interface.d.cts

@@ -0,0 +1,16 @@
+import { AuthenticateWithOptionsBase, SerializedAuthenticatePublicClientBase } from "./authenticate-with-options-base.interface.cjs";
+
+//#region src/user-management/interfaces/authenticate-with-refresh-token-public-client-options.interface.d.ts
+/** Options for refreshing tokens as a public client (no client_secret required) */
+interface AuthenticateWithRefreshTokenPublicClientOptions extends AuthenticateWithOptionsBase {
+  refreshToken: string;
+  organizationId?: string;
+}
+interface SerializedAuthenticateWithRefreshTokenPublicClientOptions extends SerializedAuthenticatePublicClientBase {
+  grant_type: 'refresh_token';
+  refresh_token: string;
+  organization_id: string | undefined;
+}
+//#endregion
+export { AuthenticateWithRefreshTokenPublicClientOptions, SerializedAuthenticateWithRefreshTokenPublicClientOptions };
+//# sourceMappingURL=authenticate-with-refresh-token-public-client-options.interface.d.cts.map

package/lib/user-management/interfaces/authenticate-with-refresh-token-public-client-options.interface.d.ts

@@ -0,0 +1,16 @@
+import { AuthenticateWithOptionsBase, SerializedAuthenticatePublicClientBase } from "./authenticate-with-options-base.interface.js";
+
+//#region src/user-management/interfaces/authenticate-with-refresh-token-public-client-options.interface.d.ts
+/** Options for refreshing tokens as a public client (no client_secret required) */
+interface AuthenticateWithRefreshTokenPublicClientOptions extends AuthenticateWithOptionsBase {
+  refreshToken: string;
+  organizationId?: string;
+}
+interface SerializedAuthenticateWithRefreshTokenPublicClientOptions extends SerializedAuthenticatePublicClientBase {
+  grant_type: 'refresh_token';
+  refresh_token: string;
+  organization_id: string | undefined;
+}
+//#endregion
+export { AuthenticateWithRefreshTokenPublicClientOptions, SerializedAuthenticateWithRefreshTokenPublicClientOptions };
+//# sourceMappingURL=authenticate-with-refresh-token-public-client-options.interface.d.ts.map

package/lib/user-management/interfaces/authenticate-with-refresh-token-public-client-options.interface.js

@@ -0,0 +1 @@
+export {  };

package/lib/user-management/interfaces/authorization-url-options.interface.d.cts

@@ -1,8 +1,17 @@
 //#region src/user-management/interfaces/authorization-url-options.interface.d.ts
-interface UserManagementAuthorizationURLOptions {
-  clientId: string;
-  codeChallenge?: string;
-  codeChallengeMethod?: 'S256';
+/**
+ * PKCE fields must be provided together or not at all.
+ * Use workos.pkce.generate() to create a valid pair.
+ */
+type PKCEFields = {
+  codeChallenge?: never;
+  codeChallengeMethod?: never;
+} | {
+  codeChallenge: string;
+  codeChallengeMethod: 'S256';
+};
+interface UserManagementAuthorizationURLBaseOptions {
+  clientId?: string;
   connectionId?: string;
   organizationId?: string;
   domainHint?: string;
@@ -15,6 +24,22 @@ interface UserManagementAuthorizationURLOptions {
   state?: string;
   screenHint?: 'sign-up' | 'sign-in';
 }
+type UserManagementAuthorizationURLOptions = UserManagementAuthorizationURLBaseOptions & PKCEFields;
+/**
+ * Result of getAuthorizationUrlWithPKCE() containing the URL,
+ * state, and PKCE code verifier.
+ *
+ * The codeVerifier must be stored securely and passed to
+ * authenticateWithCode() during token exchange.
+ */
+interface PKCEAuthorizationURLResult {
+  /** The complete authorization URL to redirect the user to */
+  url: string;
+  /** The state parameter (auto-generated) */
+  state: string;
+  /** The PKCE code verifier. Store securely and pass to authenticateWithCode(). */
+  codeVerifier: string;
+}
 //#endregion
-export { UserManagementAuthorizationURLOptions };
+export { PKCEAuthorizationURLResult, UserManagementAuthorizationURLOptions };
 //# sourceMappingURL=authorization-url-options.interface.d.cts.map