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

package/lib/organizations/serializers/index.js

@@ -1,5 +1,5 @@
-import { deserializeOrganization } from "./organization.serializer.js";
 import { serializeCreateOrganizationOptions } from "./create-organization-options.serializer.js";
+import { deserializeOrganization } from "./organization.serializer.js";
 import { serializeUpdateOrganizationOptions } from "./update-organization-options.serializer.js";
 
 export { deserializeOrganization, serializeCreateOrganizationOptions, serializeUpdateOrganizationOptions };

package/lib/pkce/pkce.cjs

@@ -0,0 +1,54 @@
+
+//#region src/pkce/pkce.ts
+/**
+* PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0 public clients.
+*
+* Implements RFC 7636 for secure authorization code exchange without a client secret.
+* Used by Electron apps, React Native/mobile apps, CLI tools, and other public clients.
+*/
+var PKCE = class {
+	/**
+	* Generate a cryptographically random code verifier.
+	*
+	* @param length - Length of verifier (43-128, default 43)
+	* @returns RFC 7636 compliant code verifier
+	*/
+	generateCodeVerifier(length = 43) {
+		if (length < 43 || length > 128) throw new RangeError(`Code verifier length must be between 43 and 128, got ${length}`);
+		const byteLength = Math.ceil(length * 3 / 4);
+		const randomBytes = new Uint8Array(byteLength);
+		crypto.getRandomValues(randomBytes);
+		return this.base64UrlEncode(randomBytes).slice(0, length);
+	}
+	/**
+	* Generate S256 code challenge from a verifier.
+	*
+	* @param verifier - The code verifier
+	* @returns Base64URL-encoded SHA256 hash
+	*/
+	async generateCodeChallenge(verifier) {
+		const data = new TextEncoder().encode(verifier);
+		const hash = await crypto.subtle.digest("SHA-256", data);
+		return this.base64UrlEncode(new Uint8Array(hash));
+	}
+	/**
+	* Generate a complete PKCE pair (verifier + challenge).
+	*
+	* @returns Code verifier, challenge, and method ('S256')
+	*/
+	async generate() {
+		const codeVerifier = this.generateCodeVerifier();
+		return {
+			codeVerifier,
+			codeChallenge: await this.generateCodeChallenge(codeVerifier),
+			codeChallengeMethod: "S256"
+		};
+	}
+	base64UrlEncode(buffer) {
+		return btoa(String.fromCharCode(...buffer)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+	}
+};
+
+//#endregion
+exports.PKCE = PKCE;
+//# sourceMappingURL=pkce.cjs.map

package/lib/pkce/pkce.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.cjs","names":[],"sources":["../../src/pkce/pkce.ts"],"sourcesContent":["export interface PKCEPair {\n  codeVerifier: string;\n  codeChallenge: string;\n  codeChallengeMethod: 'S256';\n}\n\n/**\n * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0 public clients.\n *\n * Implements RFC 7636 for secure authorization code exchange without a client secret.\n * Used by Electron apps, React Native/mobile apps, CLI tools, and other public clients.\n */\nexport class PKCE {\n  /**\n   * Generate a cryptographically random code verifier.\n   *\n   * @param length - Length of verifier (43-128, default 43)\n   * @returns RFC 7636 compliant code verifier\n   */\n  generateCodeVerifier(length: number = 43): string {\n    if (length < 43 || length > 128) {\n      throw new RangeError(\n        `Code verifier length must be between 43 and 128, got ${length}`,\n      );\n    }\n\n    const byteLength = Math.ceil((length * 3) / 4);\n    const randomBytes = new Uint8Array(byteLength);\n    crypto.getRandomValues(randomBytes);\n\n    return this.base64UrlEncode(randomBytes).slice(0, length);\n  }\n\n  /**\n   * Generate S256 code challenge from a verifier.\n   *\n   * @param verifier - The code verifier\n   * @returns Base64URL-encoded SHA256 hash\n   */\n  async generateCodeChallenge(verifier: string): Promise<string> {\n    const encoder = new TextEncoder();\n    const data = encoder.encode(verifier);\n    const hash = await crypto.subtle.digest('SHA-256', data);\n    return this.base64UrlEncode(new Uint8Array(hash));\n  }\n\n  /**\n   * Generate a complete PKCE pair (verifier + challenge).\n   *\n   * @returns Code verifier, challenge, and method ('S256')\n   */\n  async generate(): Promise<PKCEPair> {\n    const codeVerifier = this.generateCodeVerifier();\n    const codeChallenge = await this.generateCodeChallenge(codeVerifier);\n    return { codeVerifier, codeChallenge, codeChallengeMethod: 'S256' };\n  }\n\n  private base64UrlEncode(buffer: Uint8Array): string {\n    const base64 = btoa(String.fromCharCode(...buffer));\n    return base64.replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n  }\n}\n"],"mappings":";;;;;;;;AAYA,IAAa,OAAb,MAAkB;;;;;;;CAOhB,qBAAqB,SAAiB,IAAY;AAChD,MAAI,SAAS,MAAM,SAAS,IAC1B,OAAM,IAAI,WACR,wDAAwD,SACzD;EAGH,MAAM,aAAa,KAAK,KAAM,SAAS,IAAK,EAAE;EAC9C,MAAM,cAAc,IAAI,WAAW,WAAW;AAC9C,SAAO,gBAAgB,YAAY;AAEnC,SAAO,KAAK,gBAAgB,YAAY,CAAC,MAAM,GAAG,OAAO;;;;;;;;CAS3D,MAAM,sBAAsB,UAAmC;EAE7D,MAAM,OADU,IAAI,aAAa,CACZ,OAAO,SAAS;EACrC,MAAM,OAAO,MAAM,OAAO,OAAO,OAAO,WAAW,KAAK;AACxD,SAAO,KAAK,gBAAgB,IAAI,WAAW,KAAK,CAAC;;;;;;;CAQnD,MAAM,WAA8B;EAClC,MAAM,eAAe,KAAK,sBAAsB;AAEhD,SAAO;GAAE;GAAc,eADD,MAAM,KAAK,sBAAsB,aAAa;GAC9B,qBAAqB;GAAQ;;CAGrE,AAAQ,gBAAgB,QAA4B;AAElD,SADe,KAAK,OAAO,aAAa,GAAG,OAAO,CAAC,CACrC,QAAQ,OAAO,IAAI,CAAC,QAAQ,OAAO,IAAI,CAAC,QAAQ,OAAO,GAAG"}

package/lib/pkce/pkce.d.cts

@@ -0,0 +1,38 @@
+//#region src/pkce/pkce.d.ts
+interface PKCEPair {
+  codeVerifier: string;
+  codeChallenge: string;
+  codeChallengeMethod: 'S256';
+}
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0 public clients.
+ *
+ * Implements RFC 7636 for secure authorization code exchange without a client secret.
+ * Used by Electron apps, React Native/mobile apps, CLI tools, and other public clients.
+ */
+declare class PKCE {
+  /**
+   * Generate a cryptographically random code verifier.
+   *
+   * @param length - Length of verifier (43-128, default 43)
+   * @returns RFC 7636 compliant code verifier
+   */
+  generateCodeVerifier(length?: number): string;
+  /**
+   * Generate S256 code challenge from a verifier.
+   *
+   * @param verifier - The code verifier
+   * @returns Base64URL-encoded SHA256 hash
+   */
+  generateCodeChallenge(verifier: string): Promise<string>;
+  /**
+   * Generate a complete PKCE pair (verifier + challenge).
+   *
+   * @returns Code verifier, challenge, and method ('S256')
+   */
+  generate(): Promise<PKCEPair>;
+  private base64UrlEncode;
+}
+//#endregion
+export { PKCE, PKCEPair };
+//# sourceMappingURL=pkce.d.cts.map

package/lib/pkce/pkce.d.ts

@@ -0,0 +1,38 @@
+//#region src/pkce/pkce.d.ts
+interface PKCEPair {
+  codeVerifier: string;
+  codeChallenge: string;
+  codeChallengeMethod: 'S256';
+}
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0 public clients.
+ *
+ * Implements RFC 7636 for secure authorization code exchange without a client secret.
+ * Used by Electron apps, React Native/mobile apps, CLI tools, and other public clients.
+ */
+declare class PKCE {
+  /**
+   * Generate a cryptographically random code verifier.
+   *
+   * @param length - Length of verifier (43-128, default 43)
+   * @returns RFC 7636 compliant code verifier
+   */
+  generateCodeVerifier(length?: number): string;
+  /**
+   * Generate S256 code challenge from a verifier.
+   *
+   * @param verifier - The code verifier
+   * @returns Base64URL-encoded SHA256 hash
+   */
+  generateCodeChallenge(verifier: string): Promise<string>;
+  /**
+   * Generate a complete PKCE pair (verifier + challenge).
+   *
+   * @returns Code verifier, challenge, and method ('S256')
+   */
+  generate(): Promise<PKCEPair>;
+  private base64UrlEncode;
+}
+//#endregion
+export { PKCE, PKCEPair };
+//# sourceMappingURL=pkce.d.ts.map

package/lib/pkce/pkce.js

@@ -0,0 +1,53 @@
+//#region src/pkce/pkce.ts
+/**
+* PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0 public clients.
+*
+* Implements RFC 7636 for secure authorization code exchange without a client secret.
+* Used by Electron apps, React Native/mobile apps, CLI tools, and other public clients.
+*/
+var PKCE = class {
+	/**
+	* Generate a cryptographically random code verifier.
+	*
+	* @param length - Length of verifier (43-128, default 43)
+	* @returns RFC 7636 compliant code verifier
+	*/
+	generateCodeVerifier(length = 43) {
+		if (length < 43 || length > 128) throw new RangeError(`Code verifier length must be between 43 and 128, got ${length}`);
+		const byteLength = Math.ceil(length * 3 / 4);
+		const randomBytes = new Uint8Array(byteLength);
+		crypto.getRandomValues(randomBytes);
+		return this.base64UrlEncode(randomBytes).slice(0, length);
+	}
+	/**
+	* Generate S256 code challenge from a verifier.
+	*
+	* @param verifier - The code verifier
+	* @returns Base64URL-encoded SHA256 hash
+	*/
+	async generateCodeChallenge(verifier) {
+		const data = new TextEncoder().encode(verifier);
+		const hash = await crypto.subtle.digest("SHA-256", data);
+		return this.base64UrlEncode(new Uint8Array(hash));
+	}
+	/**
+	* Generate a complete PKCE pair (verifier + challenge).
+	*
+	* @returns Code verifier, challenge, and method ('S256')
+	*/
+	async generate() {
+		const codeVerifier = this.generateCodeVerifier();
+		return {
+			codeVerifier,
+			codeChallenge: await this.generateCodeChallenge(codeVerifier),
+			codeChallengeMethod: "S256"
+		};
+	}
+	base64UrlEncode(buffer) {
+		return btoa(String.fromCharCode(...buffer)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+	}
+};
+
+//#endregion
+export { PKCE };
+//# sourceMappingURL=pkce.js.map

package/lib/pkce/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","names":[],"sources":["../../src/pkce/pkce.ts"],"sourcesContent":["export interface PKCEPair {\n  codeVerifier: string;\n  codeChallenge: string;\n  codeChallengeMethod: 'S256';\n}\n\n/**\n * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0 public clients.\n *\n * Implements RFC 7636 for secure authorization code exchange without a client secret.\n * Used by Electron apps, React Native/mobile apps, CLI tools, and other public clients.\n */\nexport class PKCE {\n  /**\n   * Generate a cryptographically random code verifier.\n   *\n   * @param length - Length of verifier (43-128, default 43)\n   * @returns RFC 7636 compliant code verifier\n   */\n  generateCodeVerifier(length: number = 43): string {\n    if (length < 43 || length > 128) {\n      throw new RangeError(\n        `Code verifier length must be between 43 and 128, got ${length}`,\n      );\n    }\n\n    const byteLength = Math.ceil((length * 3) / 4);\n    const randomBytes = new Uint8Array(byteLength);\n    crypto.getRandomValues(randomBytes);\n\n    return this.base64UrlEncode(randomBytes).slice(0, length);\n  }\n\n  /**\n   * Generate S256 code challenge from a verifier.\n   *\n   * @param verifier - The code verifier\n   * @returns Base64URL-encoded SHA256 hash\n   */\n  async generateCodeChallenge(verifier: string): Promise<string> {\n    const encoder = new TextEncoder();\n    const data = encoder.encode(verifier);\n    const hash = await crypto.subtle.digest('SHA-256', data);\n    return this.base64UrlEncode(new Uint8Array(hash));\n  }\n\n  /**\n   * Generate a complete PKCE pair (verifier + challenge).\n   *\n   * @returns Code verifier, challenge, and method ('S256')\n   */\n  async generate(): Promise<PKCEPair> {\n    const codeVerifier = this.generateCodeVerifier();\n    const codeChallenge = await this.generateCodeChallenge(codeVerifier);\n    return { codeVerifier, codeChallenge, codeChallengeMethod: 'S256' };\n  }\n\n  private base64UrlEncode(buffer: Uint8Array): string {\n    const base64 = btoa(String.fromCharCode(...buffer));\n    return base64.replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n  }\n}\n"],"mappings":";;;;;;;AAYA,IAAa,OAAb,MAAkB;;;;;;;CAOhB,qBAAqB,SAAiB,IAAY;AAChD,MAAI,SAAS,MAAM,SAAS,IAC1B,OAAM,IAAI,WACR,wDAAwD,SACzD;EAGH,MAAM,aAAa,KAAK,KAAM,SAAS,IAAK,EAAE;EAC9C,MAAM,cAAc,IAAI,WAAW,WAAW;AAC9C,SAAO,gBAAgB,YAAY;AAEnC,SAAO,KAAK,gBAAgB,YAAY,CAAC,MAAM,GAAG,OAAO;;;;;;;;CAS3D,MAAM,sBAAsB,UAAmC;EAE7D,MAAM,OADU,IAAI,aAAa,CACZ,OAAO,SAAS;EACrC,MAAM,OAAO,MAAM,OAAO,OAAO,OAAO,WAAW,KAAK;AACxD,SAAO,KAAK,gBAAgB,IAAI,WAAW,KAAK,CAAC;;;;;;;CAQnD,MAAM,WAA8B;EAClC,MAAM,eAAe,KAAK,sBAAsB;AAEhD,SAAO;GAAE;GAAc,eADD,MAAM,KAAK,sBAAsB,aAAa;GAC9B,qBAAqB;GAAQ;;CAGrE,AAAQ,gBAAgB,QAA4B;AAElD,SADe,KAAK,OAAO,aAAa,GAAG,OAAO,CAAC,CACrC,QAAQ,OAAO,IAAI,CAAC,QAAQ,OAAO,IAAI,CAAC,QAAQ,OAAO,GAAG"}

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

@@ -1,5 +1,16 @@
 //#region src/sso/interfaces/authorization-url-options.interface.d.ts
-interface SSOAuthorizationURLBase {
+/**
+ * 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 SSOAuthorizationURLBaseFields {
   clientId: string;
   domainHint?: string;
   loginHint?: string;
@@ -8,22 +19,37 @@ interface SSOAuthorizationURLBase {
   redirectUri: string;
   state?: string;
 }
-interface SSOWithConnection extends SSOAuthorizationURLBase {
+/**
+ * Result of getAuthorizationUrlWithPKCE() containing the URL,
+ * state, and PKCE code verifier.
+ *
+ * The codeVerifier must be stored securely and passed to
+ * getProfileAndToken() during token exchange.
+ */
+interface SSOPKCEAuthorizationURLResult {
+  /** 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 getProfileAndToken(). */
+  codeVerifier: string;
+}
+type SSOWithConnection = SSOAuthorizationURLBaseFields & PKCEFields & {
   connection: string;
   organization?: never;
   provider?: never;
-}
-interface SSOWithOrganization extends SSOAuthorizationURLBase {
+};
+type SSOWithOrganization = SSOAuthorizationURLBaseFields & PKCEFields & {
   organization: string;
   connection?: never;
   provider?: never;
-}
-interface SSOWithProvider extends SSOAuthorizationURLBase {
+};
+type SSOWithProvider = SSOAuthorizationURLBaseFields & PKCEFields & {
   provider: string;
   connection?: never;
   organization?: never;
-}
+};
 type SSOAuthorizationURLOptions = SSOWithConnection | SSOWithOrganization | SSOWithProvider;
 //#endregion
-export { SSOAuthorizationURLOptions };
+export { SSOAuthorizationURLOptions, SSOPKCEAuthorizationURLResult };
 //# sourceMappingURL=authorization-url-options.interface.d.cts.map

package/lib/sso/interfaces/authorization-url-options.interface.d.ts

@@ -1,5 +1,16 @@
 //#region src/sso/interfaces/authorization-url-options.interface.d.ts
-interface SSOAuthorizationURLBase {
+/**
+ * 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 SSOAuthorizationURLBaseFields {
   clientId: string;
   domainHint?: string;
   loginHint?: string;
@@ -8,22 +19,37 @@ interface SSOAuthorizationURLBase {
   redirectUri: string;
   state?: string;
 }
-interface SSOWithConnection extends SSOAuthorizationURLBase {
+/**
+ * Result of getAuthorizationUrlWithPKCE() containing the URL,
+ * state, and PKCE code verifier.
+ *
+ * The codeVerifier must be stored securely and passed to
+ * getProfileAndToken() during token exchange.
+ */
+interface SSOPKCEAuthorizationURLResult {
+  /** 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 getProfileAndToken(). */
+  codeVerifier: string;
+}
+type SSOWithConnection = SSOAuthorizationURLBaseFields & PKCEFields & {
   connection: string;
   organization?: never;
   provider?: never;
-}
-interface SSOWithOrganization extends SSOAuthorizationURLBase {
+};
+type SSOWithOrganization = SSOAuthorizationURLBaseFields & PKCEFields & {
   organization: string;
   connection?: never;
   provider?: never;
-}
-interface SSOWithProvider extends SSOAuthorizationURLBase {
+};
+type SSOWithProvider = SSOAuthorizationURLBaseFields & PKCEFields & {
   provider: string;
   connection?: never;
   organization?: never;
-}
+};
 type SSOAuthorizationURLOptions = SSOWithConnection | SSOWithOrganization | SSOWithProvider;
 //#endregion
-export { SSOAuthorizationURLOptions };
+export { SSOAuthorizationURLOptions, SSOPKCEAuthorizationURLResult };
 //# sourceMappingURL=authorization-url-options.interface.d.ts.map

package/lib/sso/interfaces/get-profile-and-token-options.interface.d.cts

@@ -2,6 +2,12 @@
 interface GetProfileAndTokenOptions {
   clientId: string;
   code: string;
+  /**
+   * PKCE code verifier for public clients.
+   * Pass the codeVerifier that was generated with getAuthorizationUrlWithPKCE().
+   * When provided, client_secret is not sent (public client mode).
+   */
+  codeVerifier?: string;
 }
 //#endregion
 export { GetProfileAndTokenOptions };

package/lib/sso/interfaces/get-profile-and-token-options.interface.d.ts

@@ -2,6 +2,12 @@
 interface GetProfileAndTokenOptions {
   clientId: string;
   code: string;
+  /**
+   * PKCE code verifier for public clients.
+   * Pass the codeVerifier that was generated with getAuthorizationUrlWithPKCE().
+   * When provided, client_secret is not sent (public client mode).
+   */
+  codeVerifier?: string;
 }
 //#endregion
 export { GetProfileAndTokenOptions };

package/lib/sso/interfaces/index.d.cts

@@ -1,4 +1,4 @@
-import { SSOAuthorizationURLOptions } from "./authorization-url-options.interface.cjs";
+import { SSOAuthorizationURLOptions, SSOPKCEAuthorizationURLResult } from "./authorization-url-options.interface.cjs";
 import { ConnectionType } from "./connection-type.enum.cjs";
 import { Connection, ConnectionDomain, ConnectionResponse } from "./connection.interface.cjs";
 import { GetProfileOptions } from "./get-profile-options.interface.cjs";
@@ -6,4 +6,4 @@ import { GetProfileAndTokenOptions } from "./get-profile-and-token-options.inter
 import { ListConnectionsOptions, SerializedListConnectionsOptions } from "./list-connections-options.interface.cjs";
 import { Profile, ProfileResponse } from "./profile.interface.cjs";
 import { ProfileAndToken, ProfileAndTokenResponse } from "./profile-and-token.interface.cjs";
-export { Connection, ConnectionDomain, ConnectionResponse, ConnectionType, GetProfileAndTokenOptions, GetProfileOptions, ListConnectionsOptions, Profile, ProfileAndToken, ProfileAndTokenResponse, ProfileResponse, SSOAuthorizationURLOptions, SerializedListConnectionsOptions };
+export { Connection, ConnectionDomain, ConnectionResponse, ConnectionType, GetProfileAndTokenOptions, GetProfileOptions, ListConnectionsOptions, Profile, ProfileAndToken, ProfileAndTokenResponse, ProfileResponse, SSOAuthorizationURLOptions, type SSOPKCEAuthorizationURLResult, SerializedListConnectionsOptions };

package/lib/sso/interfaces/index.d.ts

@@ -1,4 +1,4 @@
-import { SSOAuthorizationURLOptions } from "./authorization-url-options.interface.js";
+import { SSOAuthorizationURLOptions, SSOPKCEAuthorizationURLResult } from "./authorization-url-options.interface.js";
 import { ConnectionType } from "./connection-type.enum.js";
 import { Connection, ConnectionDomain, ConnectionResponse } from "./connection.interface.js";
 import { GetProfileOptions } from "./get-profile-options.interface.js";
@@ -6,4 +6,4 @@ import { GetProfileAndTokenOptions } from "./get-profile-and-token-options.inter
 import { ListConnectionsOptions, SerializedListConnectionsOptions } from "./list-connections-options.interface.js";
 import { Profile, ProfileResponse } from "./profile.interface.js";
 import { ProfileAndToken, ProfileAndTokenResponse } from "./profile-and-token.interface.js";
-export { Connection, ConnectionDomain, ConnectionResponse, ConnectionType, GetProfileAndTokenOptions, GetProfileOptions, ListConnectionsOptions, Profile, ProfileAndToken, ProfileAndTokenResponse, ProfileResponse, SSOAuthorizationURLOptions, SerializedListConnectionsOptions };
+export { Connection, ConnectionDomain, ConnectionResponse, ConnectionType, GetProfileAndTokenOptions, GetProfileOptions, ListConnectionsOptions, Profile, ProfileAndToken, ProfileAndTokenResponse, ProfileResponse, SSOAuthorizationURLOptions, type SSOPKCEAuthorizationURLResult, SerializedListConnectionsOptions };

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