feat(js): add clerk.oauthApplication.getConsentInfo

.changeset/few-stamps-retire.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+---
+
+Add `OAuthApplication` resource and `getConsentInfo()` method for retrieving OAuth consent information, enabling custom OAuth consent flows.

packages/clerk-js/src/core/clerk.ts

@@ -88,6 +88,7 @@ import type {
  ListenerOptions,
  LoadedClerk,
  NavigateOptions,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -178,7 +179,7 @@ import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
 import { Protect } from './protect';
-import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
+import { BaseResource, Client, Environment, OAuthApplication, Organization, Waitlist } from './resources/internal';
 import { State } from './state';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -224,6 +225,7 @@ export class Clerk implements ClerkInterface {
 
  private static _billing: BillingNamespace;
  private static _apiKeys: APIKeysNamespace;
+ private static _oauthApplication: OAuthApplicationNamespace;
  private _checkout: ClerkInterface['__experimental_checkout'] | undefined;
 
  public client: ClientResource | undefined;
@@ -403,6 +405,15 @@ export class Clerk implements ClerkInterface {
  return Clerk._apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace {
+ if (!Clerk._oauthApplication) {
+ Clerk._oauthApplication = {
+ getConsentInfo: params => OAuthApplication.getConsentInfo(params),
+ };
+ }
+ return Clerk._oauthApplication;
+ }
+
  __experimental_checkout(options: __experimental_CheckoutOptions): CheckoutSignalValue {
  if (!this._checkout) {
  this._checkout = (params: any) => createCheckoutInstance(this, params);

packages/clerk-js/src/core/resources/OAuthApplication.ts

@@ -0,0 +1,49 @@
+import { ClerkRuntimeError } from '@clerk/shared/error';
+import type {
+ ClerkResourceJSON,
+ GetOAuthConsentInfoParams,
+ OAuthConsentInfo,
+ OAuthConsentInfoJSON,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class OAuthApplication extends BaseResource {
+ pathRoot = '';
+
+ protected fromJSON(_data: ClerkResourceJSON | null): this {
+ return this;
+ }
+
+ static async getConsentInfo(params: GetOAuthConsentInfoParams): Promise<OAuthConsentInfo> {
+ const { oauthClientId, scope } = params;
+ const json = await BaseResource._fetch<OAuthConsentInfoJSON>(
+ {
+ method: 'GET',
+ path: `/me/oauth/consent/${encodeURIComponent(oauthClientId)}`,
+ search: scope !== undefined ? { scope } : undefined,
+ },
+ { skipUpdateClient: true },
+ );
+
+ if (!json) {
+ throw new ClerkRuntimeError('Network request failed while offline', { code: 'network_error' });
+ }
+
+ // Handle in case we start wrapping the response in the future
+ const data = json.response ?? json;
+ return {
+ oauthApplicationName: data.oauth_application_name,
+ oauthApplicationLogoUrl: data.oauth_application_logo_url,
+ oauthApplicationUrl: data.oauth_application_url,
+ clientId: data.client_id,
+ state: data.state,
+ scopes:
+ data.scopes?.map(scope => ({
+ scope: scope.scope,
+ description: scope.description,
+ requiresConsent: scope.requires_consent,
+ })) ?? [],
+ };
+ }
+}

packages/clerk-js/src/core/resources/__tests__/OAuthApplication.test.ts

@@ -0,0 +1,149 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import type { InstanceType, OAuthConsentInfoJSON } from '@clerk/shared/types';
+import { afterEach, describe, expect, it, type Mock, vi } from 'vitest';
+
+import { mockFetch } from '@/test/core-fixtures';
+
+import { SUPPORTED_FAPI_VERSION } from '../../constants';
+import { createFapiClient } from '../../fapiClient';
+import { BaseResource } from '../internal';
+import { OAuthApplication } from '../OAuthApplication';
+
+const consentPayload: OAuthConsentInfoJSON = {
+ object: 'oauth_consent_info',
+ id: 'client_abc',
+ oauth_application_name: 'My App',
+ oauth_application_logo_url: 'https://img.example/logo.png',
+ oauth_application_url: 'https://app.example',
+ client_id: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requires_consent: true }],
+};
+
+describe('OAuthApplication.getConsentInfo', () => {
+ afterEach(() => {
+ (global.fetch as Mock)?.mockClear?.();
+ BaseResource.clerk = null as any;
+ vi.restoreAllMocks();
+ });
+
+ it('calls BaseResource._fetch with GET, encoded path, optional scope, and skipUpdateClient', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'my/client id', scope: 'openid email' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ {
+ method: 'GET',
+ path: '/me/oauth/consent/my%2Fclient%20id',
+ search: { scope: 'openid email' },
+ },
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('omits search when scope is undefined', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'cid' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ search: undefined,
+ }),
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(consentPayload as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response (enveloped)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('defaults scopes to an empty array when absent', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: { ...consentPayload, scopes: undefined },
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+ expect(info.scopes).toEqual([]);
+ });
+
+ it('maps ClerkAPIResponseError from FAPI on non-2xx', async () => {
+ mockFetch(false, 422, {
+ errors: [{ code: 'oauth_consent_error', long_message: 'Consent metadata unavailable' }],
+ });
+
+ BaseResource.clerk = {
+ getFapiClient: () =>
+ createFapiClient({
+ frontendApi: 'clerk.example.com',
+ getSessionId: () => undefined,
+ instanceType: 'development' as InstanceType,
+ }),
+ __internal_setCountry: vi.fn(),
+ handleUnauthenticated: vi.fn(),
+ __internal_handleUnauthenticatedDevBrowser: vi.fn(),
+ } as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toSatisfy(
+ (err: unknown) => err instanceof ClerkAPIResponseError && err.message === 'Consent metadata unavailable',
+ );
+
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain(`/v1/me/oauth/consent/cid`);
+ expect(url.toString()).toContain(`__clerk_api_version=${SUPPORTED_FAPI_VERSION}`);
+ });
+
+ it('throws ClerkRuntimeError when _fetch returns null (offline)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(null);
+
+ BaseResource.clerk = {} as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toMatchObject({
+ code: 'network_error',
+ });
+ });
+});

packages/clerk-js/src/core/resources/internal.ts

@@ -22,6 +22,7 @@ export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';
 export * from './Image';
+export * from './OAuthApplication';
 export * from './Organization';
 export * from './OrganizationDomain';
 export * from './OrganizationInvitation';

packages/react/src/isomorphicClerk.ts

@@ -35,6 +35,7 @@ import type {
  ListenerCallback,
  ListenerOptions,
  LoadedClerk,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -118,11 +119,13 @@ type IsomorphicLoadedClerk = Without<
  | '__internal_reloadInitialResources'
  | 'billing'
  | 'apiKeys'
+ | 'oauthApplication'
  | '__internal_setActiveInProgress'
 > & {
  client: ClientResource | undefined;
  billing: BillingNamespace | undefined;
  apiKeys: APIKeysNamespace | undefined;
+ oauthApplication: OAuthApplicationNamespace | undefined;
 };
 
 export class IsomorphicClerk implements IsomorphicLoadedClerk {
@@ -844,6 +847,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace | undefined {
+ return this.clerkjs?.oauthApplication;
+ }
+
  __experimental_checkout = (...args: Parameters<Clerk['__experimental_checkout']>) => {
  return this.loaded && this.clerkjs
  ? this.clerkjs.__experimental_checkout(...args)

packages/shared/src/types/clerk.ts

@@ -19,6 +19,7 @@ import type { DisplayThemeJSON } from './json';
 import type { LocalizationResource } from './localization';
 import type { DomainOrProxyUrl, MultiDomainAndOrProxy } from './multiDomain';
 import type { OAuthProvider, OAuthScope } from './oauth';
+import type { OAuthApplicationNamespace } from './oauthApplication';
 import type { OrganizationResource } from './organization';
 import type { OrganizationCustomRoleKey } from './organizationMembership';
 import type { ClerkPaginationParams } from './pagination';
@@ -168,6 +169,7 @@ export type SetActiveNavigate = (params: {
  session: SessionResource;
  /**
  * Decorate the destination URL to enable Safari ITP cookie refresh when needed.
+ *
  * @see {@link DecorateUrl}
  */
  decorateUrl: DecorateUrl;
@@ -1027,6 +1029,11 @@ export interface Clerk {
  */
  apiKeys: APIKeysNamespace;
 
+ /**
+ * OAuth application helpers (e.g. consent metadata for custom consent UIs).
+ */
+ oauthApplication: OAuthApplicationNamespace;
+
  /**
  * Checkout API
  *
@@ -2496,21 +2503,25 @@ export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
  Clerk?: ClerkProp;
  /**
  * The URL that `@clerk/clerk-js` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkJSUrl?: string;
  /**
  * The npm version for `@clerk/clerk-js`.
+ *
  * @internal
  */
  __internal_clerkJSVersion?: string;
  /**
  * The URL that `@clerk/ui` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkUIUrl?: string;
  /**
  * The npm version for `@clerk/ui`.
+ *
  * @internal
  */
  __internal_clerkUIVersion?: string;

packages/shared/src/types/index.ts

@@ -33,6 +33,7 @@ export type * from './key';
 export type * from './localization';
 export type * from './multiDomain';
 export type * from './oauth';
+export type * from './oauthApplication';
 export type * from './organization';
 export type * from './organizationCreationDefaults';
 export type * from './organizationDomain';

.changeset/few-stamps-retire.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+---
+
+Add `OAuthApplication` resource and `getConsentInfo()` method for retrieving OAuth consent information, enabling custom OAuth consent flows.

packages/clerk-js/src/core/clerk.ts

@@ -88,6 +88,7 @@ import type {
  ListenerOptions,
  LoadedClerk,
  NavigateOptions,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -178,7 +179,7 @@ import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
 import { Protect } from './protect';
-import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
+import { BaseResource, Client, Environment, OAuthApplication, Organization, Waitlist } from './resources/internal';
 import { State } from './state';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -224,6 +225,7 @@ export class Clerk implements ClerkInterface {
 
  private static _billing: BillingNamespace;
  private static _apiKeys: APIKeysNamespace;
+ private static _oauthApplication: OAuthApplicationNamespace;
  private _checkout: ClerkInterface['__experimental_checkout'] | undefined;
 
  public client: ClientResource | undefined;
@@ -403,6 +405,15 @@ export class Clerk implements ClerkInterface {
  return Clerk._apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace {
+ if (!Clerk._oauthApplication) {
+ Clerk._oauthApplication = {
+ getConsentInfo: params => OAuthApplication.getConsentInfo(params),
+ };
+ }
+ return Clerk._oauthApplication;
+ }
+
  __experimental_checkout(options: __experimental_CheckoutOptions): CheckoutSignalValue {
  if (!this._checkout) {
  this._checkout = (params: any) => createCheckoutInstance(this, params);

packages/clerk-js/src/core/resources/OAuthApplication.ts

@@ -0,0 +1,49 @@
+import { ClerkRuntimeError } from '@clerk/shared/error';
+import type {
+ ClerkResourceJSON,
+ GetOAuthConsentInfoParams,
+ OAuthConsentInfo,
+ OAuthConsentInfoJSON,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class OAuthApplication extends BaseResource {
+ pathRoot = '';
+
+ protected fromJSON(_data: ClerkResourceJSON | null): this {
+ return this;
+ }
+
+ static async getConsentInfo(params: GetOAuthConsentInfoParams): Promise<OAuthConsentInfo> {
+ const { oauthClientId, scope } = params;
+ const json = await BaseResource._fetch<OAuthConsentInfoJSON>(
+ {
+ method: 'GET',
+ path: `/me/oauth/consent/${encodeURIComponent(oauthClientId)}`,
+ search: scope !== undefined ? { scope } : undefined,
+ },
+ { skipUpdateClient: true },
+ );
+
+ if (!json) {
+ throw new ClerkRuntimeError('Network request failed while offline', { code: 'network_error' });
+ }
+
+ // Handle in case we start wrapping the response in the future
+ const data = json.response ?? json;
+ return {
+ oauthApplicationName: data.oauth_application_name,
+ oauthApplicationLogoUrl: data.oauth_application_logo_url,
+ oauthApplicationUrl: data.oauth_application_url,
+ clientId: data.client_id,
+ state: data.state,
+ scopes:
+ data.scopes?.map(scope => ({
+ scope: scope.scope,
+ description: scope.description,
+ requiresConsent: scope.requires_consent,
+ })) ?? [],
+ };
+ }
+}

packages/clerk-js/src/core/resources/__tests__/OAuthApplication.test.ts

@@ -0,0 +1,149 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import type { InstanceType, OAuthConsentInfoJSON } from '@clerk/shared/types';
+import { afterEach, describe, expect, it, type Mock, vi } from 'vitest';
+
+import { mockFetch } from '@/test/core-fixtures';
+
+import { SUPPORTED_FAPI_VERSION } from '../../constants';
+import { createFapiClient } from '../../fapiClient';
+import { BaseResource } from '../internal';
+import { OAuthApplication } from '../OAuthApplication';
+
+const consentPayload: OAuthConsentInfoJSON = {
+ object: 'oauth_consent_info',
+ id: 'client_abc',
+ oauth_application_name: 'My App',
+ oauth_application_logo_url: 'https://img.example/logo.png',
+ oauth_application_url: 'https://app.example',
+ client_id: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requires_consent: true }],
+};
+
+describe('OAuthApplication.getConsentInfo', () => {
+ afterEach(() => {
+ (global.fetch as Mock)?.mockClear?.();
+ BaseResource.clerk = null as any;
+ vi.restoreAllMocks();
+ });
+
+ it('calls BaseResource._fetch with GET, encoded path, optional scope, and skipUpdateClient', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'my/client id', scope: 'openid email' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ {
+ method: 'GET',
+ path: '/me/oauth/consent/my%2Fclient%20id',
+ search: { scope: 'openid email' },
+ },
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('omits search when scope is undefined', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'cid' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ search: undefined,
+ }),
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(consentPayload as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response (enveloped)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('defaults scopes to an empty array when absent', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: { ...consentPayload, scopes: undefined },
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+ expect(info.scopes).toEqual([]);
+ });
+
+ it('maps ClerkAPIResponseError from FAPI on non-2xx', async () => {
+ mockFetch(false, 422, {
+ errors: [{ code: 'oauth_consent_error', long_message: 'Consent metadata unavailable' }],
+ });
+
+ BaseResource.clerk = {
+ getFapiClient: () =>
+ createFapiClient({
+ frontendApi: 'clerk.example.com',
+ getSessionId: () => undefined,
+ instanceType: 'development' as InstanceType,
+ }),
+ __internal_setCountry: vi.fn(),
+ handleUnauthenticated: vi.fn(),
+ __internal_handleUnauthenticatedDevBrowser: vi.fn(),
+ } as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toSatisfy(
+ (err: unknown) => err instanceof ClerkAPIResponseError && err.message === 'Consent metadata unavailable',
+ );
+
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain(`/v1/me/oauth/consent/cid`);
+ expect(url.toString()).toContain(`__clerk_api_version=${SUPPORTED_FAPI_VERSION}`);
+ });
+
+ it('throws ClerkRuntimeError when _fetch returns null (offline)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(null);
+
+ BaseResource.clerk = {} as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toMatchObject({
+ code: 'network_error',
+ });
+ });
+});

packages/clerk-js/src/core/resources/internal.ts

@@ -22,6 +22,7 @@ export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';
 export * from './Image';
+export * from './OAuthApplication';
 export * from './Organization';
 export * from './OrganizationDomain';
 export * from './OrganizationInvitation';

packages/react/src/isomorphicClerk.ts

@@ -35,6 +35,7 @@ import type {
  ListenerCallback,
  ListenerOptions,
  LoadedClerk,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -118,11 +119,13 @@ type IsomorphicLoadedClerk = Without<
  | '__internal_reloadInitialResources'
  | 'billing'
  | 'apiKeys'
+ | 'oauthApplication'
  | '__internal_setActiveInProgress'
 > & {
  client: ClientResource | undefined;
  billing: BillingNamespace | undefined;
  apiKeys: APIKeysNamespace | undefined;
+ oauthApplication: OAuthApplicationNamespace | undefined;
 };
 
 export class IsomorphicClerk implements IsomorphicLoadedClerk {
@@ -844,6 +847,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace | undefined {
+ return this.clerkjs?.oauthApplication;
+ }
+
  __experimental_checkout = (...args: Parameters<Clerk['__experimental_checkout']>) => {
  return this.loaded && this.clerkjs
  ? this.clerkjs.__experimental_checkout(...args)

packages/shared/src/types/clerk.ts

@@ -19,6 +19,7 @@ import type { DisplayThemeJSON } from './json';
 import type { LocalizationResource } from './localization';
 import type { DomainOrProxyUrl, MultiDomainAndOrProxy } from './multiDomain';
 import type { OAuthProvider, OAuthScope } from './oauth';
+import type { OAuthApplicationNamespace } from './oauthApplication';
 import type { OrganizationResource } from './organization';
 import type { OrganizationCustomRoleKey } from './organizationMembership';
 import type { ClerkPaginationParams } from './pagination';
@@ -168,6 +169,7 @@ export type SetActiveNavigate = (params: {
  session: SessionResource;
  /**
  * Decorate the destination URL to enable Safari ITP cookie refresh when needed.
+ *
  * @see {@link DecorateUrl}
  */
  decorateUrl: DecorateUrl;
@@ -1027,6 +1029,11 @@ export interface Clerk {
  */
  apiKeys: APIKeysNamespace;
 
+ /**
+ * OAuth application helpers (e.g. consent metadata for custom consent UIs).
+ */
+ oauthApplication: OAuthApplicationNamespace;
+
  /**
  * Checkout API
  *
@@ -2496,21 +2503,25 @@ export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
  Clerk?: ClerkProp;
  /**
  * The URL that `@clerk/clerk-js` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkJSUrl?: string;
  /**
  * The npm version for `@clerk/clerk-js`.
+ *
  * @internal
  */
  __internal_clerkJSVersion?: string;
  /**
  * The URL that `@clerk/ui` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkUIUrl?: string;
  /**
  * The npm version for `@clerk/ui`.
+ *
  * @internal
  */
  __internal_clerkUIVersion?: string;

packages/shared/src/types/index.ts

@@ -33,6 +33,7 @@ export type * from './key';
 export type * from './localization';
 export type * from './multiDomain';
 export type * from './oauth';
+export type * from './oauthApplication';
 export type * from './organization';
 export type * from './organizationCreationDefaults';
 export type * from './organizationDomain';

.changeset/few-stamps-retire.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+---
+
+Add `OAuthApplication` resource and `getConsentInfo()` method for retrieving OAuth consent information, enabling custom OAuth consent flows.

packages/clerk-js/src/core/clerk.ts

@@ -88,6 +88,7 @@ import type {
  ListenerOptions,
  LoadedClerk,
  NavigateOptions,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -178,7 +179,7 @@ import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
 import { Protect } from './protect';
-import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
+import { BaseResource, Client, Environment, OAuthApplication, Organization, Waitlist } from './resources/internal';
 import { State } from './state';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -224,6 +225,7 @@ export class Clerk implements ClerkInterface {
 
  private static _billing: BillingNamespace;
  private static _apiKeys: APIKeysNamespace;
+ private static _oauthApplication: OAuthApplicationNamespace;
  private _checkout: ClerkInterface['__experimental_checkout'] | undefined;
 
  public client: ClientResource | undefined;
@@ -403,6 +405,15 @@ export class Clerk implements ClerkInterface {
  return Clerk._apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace {
+ if (!Clerk._oauthApplication) {
+ Clerk._oauthApplication = {
+ getConsentInfo: params => OAuthApplication.getConsentInfo(params),
+ };
+ }
+ return Clerk._oauthApplication;
+ }
+
  __experimental_checkout(options: __experimental_CheckoutOptions): CheckoutSignalValue {
  if (!this._checkout) {
  this._checkout = (params: any) => createCheckoutInstance(this, params);

packages/clerk-js/src/core/resources/OAuthApplication.ts

@@ -0,0 +1,49 @@
+import { ClerkRuntimeError } from '@clerk/shared/error';
+import type {
+ ClerkResourceJSON,
+ GetOAuthConsentInfoParams,
+ OAuthConsentInfo,
+ OAuthConsentInfoJSON,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class OAuthApplication extends BaseResource {
+ pathRoot = '';
+
+ protected fromJSON(_data: ClerkResourceJSON | null): this {
+ return this;
+ }
+
+ static async getConsentInfo(params: GetOAuthConsentInfoParams): Promise<OAuthConsentInfo> {
+ const { oauthClientId, scope } = params;
+ const json = await BaseResource._fetch<OAuthConsentInfoJSON>(
+ {
+ method: 'GET',
+ path: `/me/oauth/consent/${encodeURIComponent(oauthClientId)}`,
+ search: scope !== undefined ? { scope } : undefined,
+ },
+ { skipUpdateClient: true },
+ );
+
+ if (!json) {
+ throw new ClerkRuntimeError('Network request failed while offline', { code: 'network_error' });
+ }
+
+ // Handle in case we start wrapping the response in the future
+ const data = json.response ?? json;
+ return {
+ oauthApplicationName: data.oauth_application_name,
+ oauthApplicationLogoUrl: data.oauth_application_logo_url,
+ oauthApplicationUrl: data.oauth_application_url,
+ clientId: data.client_id,
+ state: data.state,
+ scopes:
+ data.scopes?.map(scope => ({
+ scope: scope.scope,
+ description: scope.description,
+ requiresConsent: scope.requires_consent,
+ })) ?? [],
+ };
+ }
+}

packages/clerk-js/src/core/resources/__tests__/OAuthApplication.test.ts

@@ -0,0 +1,149 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import type { InstanceType, OAuthConsentInfoJSON } from '@clerk/shared/types';
+import { afterEach, describe, expect, it, type Mock, vi } from 'vitest';
+
+import { mockFetch } from '@/test/core-fixtures';
+
+import { SUPPORTED_FAPI_VERSION } from '../../constants';
+import { createFapiClient } from '../../fapiClient';
+import { BaseResource } from '../internal';
+import { OAuthApplication } from '../OAuthApplication';
+
+const consentPayload: OAuthConsentInfoJSON = {
+ object: 'oauth_consent_info',
+ id: 'client_abc',
+ oauth_application_name: 'My App',
+ oauth_application_logo_url: 'https://img.example/logo.png',
+ oauth_application_url: 'https://app.example',
+ client_id: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requires_consent: true }],
+};
+
+describe('OAuthApplication.getConsentInfo', () => {
+ afterEach(() => {
+ (global.fetch as Mock)?.mockClear?.();
+ BaseResource.clerk = null as any;
+ vi.restoreAllMocks();
+ });
+
+ it('calls BaseResource._fetch with GET, encoded path, optional scope, and skipUpdateClient', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'my/client id', scope: 'openid email' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ {
+ method: 'GET',
+ path: '/me/oauth/consent/my%2Fclient%20id',
+ search: { scope: 'openid email' },
+ },
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('omits search when scope is undefined', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'cid' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ search: undefined,
+ }),
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(consentPayload as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response (enveloped)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('defaults scopes to an empty array when absent', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: { ...consentPayload, scopes: undefined },
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+ expect(info.scopes).toEqual([]);
+ });
+
+ it('maps ClerkAPIResponseError from FAPI on non-2xx', async () => {
+ mockFetch(false, 422, {
+ errors: [{ code: 'oauth_consent_error', long_message: 'Consent metadata unavailable' }],
+ });
+
+ BaseResource.clerk = {
+ getFapiClient: () =>
+ createFapiClient({
+ frontendApi: 'clerk.example.com',
+ getSessionId: () => undefined,
+ instanceType: 'development' as InstanceType,
+ }),
+ __internal_setCountry: vi.fn(),
+ handleUnauthenticated: vi.fn(),
+ __internal_handleUnauthenticatedDevBrowser: vi.fn(),
+ } as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toSatisfy(
+ (err: unknown) => err instanceof ClerkAPIResponseError && err.message === 'Consent metadata unavailable',
+ );
+
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain(`/v1/me/oauth/consent/cid`);
+ expect(url.toString()).toContain(`__clerk_api_version=${SUPPORTED_FAPI_VERSION}`);
+ });
+
+ it('throws ClerkRuntimeError when _fetch returns null (offline)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(null);
+
+ BaseResource.clerk = {} as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toMatchObject({
+ code: 'network_error',
+ });
+ });
+});

packages/clerk-js/src/core/resources/internal.ts

@@ -22,6 +22,7 @@ export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';
 export * from './Image';
+export * from './OAuthApplication';
 export * from './Organization';
 export * from './OrganizationDomain';
 export * from './OrganizationInvitation';

packages/react/src/isomorphicClerk.ts

@@ -35,6 +35,7 @@ import type {
  ListenerCallback,
  ListenerOptions,
  LoadedClerk,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -118,11 +119,13 @@ type IsomorphicLoadedClerk = Without<
  | '__internal_reloadInitialResources'
  | 'billing'
  | 'apiKeys'
+ | 'oauthApplication'
  | '__internal_setActiveInProgress'
 > & {
  client: ClientResource | undefined;
  billing: BillingNamespace | undefined;
  apiKeys: APIKeysNamespace | undefined;
+ oauthApplication: OAuthApplicationNamespace | undefined;
 };
 
 export class IsomorphicClerk implements IsomorphicLoadedClerk {
@@ -844,6 +847,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace | undefined {
+ return this.clerkjs?.oauthApplication;
+ }
+
  __experimental_checkout = (...args: Parameters<Clerk['__experimental_checkout']>) => {
  return this.loaded && this.clerkjs
  ? this.clerkjs.__experimental_checkout(...args)

packages/shared/src/types/clerk.ts

@@ -19,6 +19,7 @@ import type { DisplayThemeJSON } from './json';
 import type { LocalizationResource } from './localization';
 import type { DomainOrProxyUrl, MultiDomainAndOrProxy } from './multiDomain';
 import type { OAuthProvider, OAuthScope } from './oauth';
+import type { OAuthApplicationNamespace } from './oauthApplication';
 import type { OrganizationResource } from './organization';
 import type { OrganizationCustomRoleKey } from './organizationMembership';
 import type { ClerkPaginationParams } from './pagination';
@@ -168,6 +169,7 @@ export type SetActiveNavigate = (params: {
  session: SessionResource;
  /**
  * Decorate the destination URL to enable Safari ITP cookie refresh when needed.
+ *
  * @see {@link DecorateUrl}
  */
  decorateUrl: DecorateUrl;
@@ -1027,6 +1029,11 @@ export interface Clerk {
  */
  apiKeys: APIKeysNamespace;
 
+ /**
+ * OAuth application helpers (e.g. consent metadata for custom consent UIs).
+ */
+ oauthApplication: OAuthApplicationNamespace;
+
  /**
  * Checkout API
  *
@@ -2496,21 +2503,25 @@ export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
  Clerk?: ClerkProp;
  /**
  * The URL that `@clerk/clerk-js` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkJSUrl?: string;
  /**
  * The npm version for `@clerk/clerk-js`.
+ *
  * @internal
  */
  __internal_clerkJSVersion?: string;
  /**
  * The URL that `@clerk/ui` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkUIUrl?: string;
  /**
  * The npm version for `@clerk/ui`.
+ *
  * @internal
  */
  __internal_clerkUIVersion?: string;

packages/shared/src/types/index.ts

@@ -33,6 +33,7 @@ export type * from './key';
 export type * from './localization';
 export type * from './multiDomain';
 export type * from './oauth';
+export type * from './oauthApplication';
 export type * from './organization';
 export type * from './organizationCreationDefaults';
 export type * from './organizationDomain';

.changeset/few-stamps-retire.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+---
+
+Add `OAuthApplication` resource and `getConsentInfo()` method for retrieving OAuth consent information, enabling custom OAuth consent flows.

packages/clerk-js/src/core/clerk.ts

@@ -88,6 +88,7 @@ import type {
  ListenerOptions,
  LoadedClerk,
  NavigateOptions,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -178,7 +179,7 @@ import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
 import { Protect } from './protect';
-import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
+import { BaseResource, Client, Environment, OAuthApplication, Organization, Waitlist } from './resources/internal';
 import { State } from './state';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -224,6 +225,7 @@ export class Clerk implements ClerkInterface {
 
  private static _billing: BillingNamespace;
  private static _apiKeys: APIKeysNamespace;
+ private static _oauthApplication: OAuthApplicationNamespace;
  private _checkout: ClerkInterface['__experimental_checkout'] | undefined;
 
  public client: ClientResource | undefined;
@@ -403,6 +405,15 @@ export class Clerk implements ClerkInterface {
  return Clerk._apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace {
+ if (!Clerk._oauthApplication) {
+ Clerk._oauthApplication = {
+ getConsentInfo: params => OAuthApplication.getConsentInfo(params),
+ };
+ }
+ return Clerk._oauthApplication;
+ }
+
  __experimental_checkout(options: __experimental_CheckoutOptions): CheckoutSignalValue {
  if (!this._checkout) {
  this._checkout = (params: any) => createCheckoutInstance(this, params);

packages/clerk-js/src/core/resources/OAuthApplication.ts

@@ -0,0 +1,49 @@
+import { ClerkRuntimeError } from '@clerk/shared/error';
+import type {
+ ClerkResourceJSON,
+ GetOAuthConsentInfoParams,
+ OAuthConsentInfo,
+ OAuthConsentInfoJSON,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class OAuthApplication extends BaseResource {
+ pathRoot = '';
+
+ protected fromJSON(_data: ClerkResourceJSON | null): this {
+ return this;
+ }
+
+ static async getConsentInfo(params: GetOAuthConsentInfoParams): Promise<OAuthConsentInfo> {
+ const { oauthClientId, scope } = params;
+ const json = await BaseResource._fetch<OAuthConsentInfoJSON>(
+ {
+ method: 'GET',
+ path: `/me/oauth/consent/${encodeURIComponent(oauthClientId)}`,
+ search: scope !== undefined ? { scope } : undefined,
+ },
+ { skipUpdateClient: true },
+ );
+
+ if (!json) {
+ throw new ClerkRuntimeError('Network request failed while offline', { code: 'network_error' });
+ }
+
+ // Handle in case we start wrapping the response in the future
+ const data = json.response ?? json;
+ return {
+ oauthApplicationName: data.oauth_application_name,
+ oauthApplicationLogoUrl: data.oauth_application_logo_url,
+ oauthApplicationUrl: data.oauth_application_url,
+ clientId: data.client_id,
+ state: data.state,
+ scopes:
+ data.scopes?.map(scope => ({
+ scope: scope.scope,
+ description: scope.description,
+ requiresConsent: scope.requires_consent,
+ })) ?? [],
+ };
+ }
+}

packages/clerk-js/src/core/resources/__tests__/OAuthApplication.test.ts

@@ -0,0 +1,149 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import type { InstanceType, OAuthConsentInfoJSON } from '@clerk/shared/types';
+import { afterEach, describe, expect, it, type Mock, vi } from 'vitest';
+
+import { mockFetch } from '@/test/core-fixtures';
+
+import { SUPPORTED_FAPI_VERSION } from '../../constants';
+import { createFapiClient } from '../../fapiClient';
+import { BaseResource } from '../internal';
+import { OAuthApplication } from '../OAuthApplication';
+
+const consentPayload: OAuthConsentInfoJSON = {
+ object: 'oauth_consent_info',
+ id: 'client_abc',
+ oauth_application_name: 'My App',
+ oauth_application_logo_url: 'https://img.example/logo.png',
+ oauth_application_url: 'https://app.example',
+ client_id: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requires_consent: true }],
+};
+
+describe('OAuthApplication.getConsentInfo', () => {
+ afterEach(() => {
+ (global.fetch as Mock)?.mockClear?.();
+ BaseResource.clerk = null as any;
+ vi.restoreAllMocks();
+ });
+
+ it('calls BaseResource._fetch with GET, encoded path, optional scope, and skipUpdateClient', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'my/client id', scope: 'openid email' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ {
+ method: 'GET',
+ path: '/me/oauth/consent/my%2Fclient%20id',
+ search: { scope: 'openid email' },
+ },
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('omits search when scope is undefined', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'cid' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ search: undefined,
+ }),
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(consentPayload as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response (enveloped)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('defaults scopes to an empty array when absent', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: { ...consentPayload, scopes: undefined },
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+ expect(info.scopes).toEqual([]);
+ });
+
+ it('maps ClerkAPIResponseError from FAPI on non-2xx', async () => {
+ mockFetch(false, 422, {
+ errors: [{ code: 'oauth_consent_error', long_message: 'Consent metadata unavailable' }],
+ });
+
+ BaseResource.clerk = {
+ getFapiClient: () =>
+ createFapiClient({
+ frontendApi: 'clerk.example.com',
+ getSessionId: () => undefined,
+ instanceType: 'development' as InstanceType,
+ }),
+ __internal_setCountry: vi.fn(),
+ handleUnauthenticated: vi.fn(),
+ __internal_handleUnauthenticatedDevBrowser: vi.fn(),
+ } as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toSatisfy(
+ (err: unknown) => err instanceof ClerkAPIResponseError && err.message === 'Consent metadata unavailable',
+ );
+
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain(`/v1/me/oauth/consent/cid`);
+ expect(url.toString()).toContain(`__clerk_api_version=${SUPPORTED_FAPI_VERSION}`);
+ });
+
+ it('throws ClerkRuntimeError when _fetch returns null (offline)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(null);
+
+ BaseResource.clerk = {} as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toMatchObject({
+ code: 'network_error',
+ });
+ });
+});

packages/clerk-js/src/core/resources/internal.ts

@@ -22,6 +22,7 @@ export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';
 export * from './Image';
+export * from './OAuthApplication';
 export * from './Organization';
 export * from './OrganizationDomain';
 export * from './OrganizationInvitation';

packages/react/src/isomorphicClerk.ts

@@ -35,6 +35,7 @@ import type {
  ListenerCallback,
  ListenerOptions,
  LoadedClerk,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -118,11 +119,13 @@ type IsomorphicLoadedClerk = Without<
  | '__internal_reloadInitialResources'
  | 'billing'
  | 'apiKeys'
+ | 'oauthApplication'
  | '__internal_setActiveInProgress'
 > & {
  client: ClientResource | undefined;
  billing: BillingNamespace | undefined;
  apiKeys: APIKeysNamespace | undefined;
+ oauthApplication: OAuthApplicationNamespace | undefined;
 };
 
 export class IsomorphicClerk implements IsomorphicLoadedClerk {
@@ -844,6 +847,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace | undefined {
+ return this.clerkjs?.oauthApplication;
+ }
+
  __experimental_checkout = (...args: Parameters<Clerk['__experimental_checkout']>) => {
  return this.loaded && this.clerkjs
  ? this.clerkjs.__experimental_checkout(...args)

packages/shared/src/types/clerk.ts

@@ -19,6 +19,7 @@ import type { DisplayThemeJSON } from './json';
 import type { LocalizationResource } from './localization';
 import type { DomainOrProxyUrl, MultiDomainAndOrProxy } from './multiDomain';
 import type { OAuthProvider, OAuthScope } from './oauth';
+import type { OAuthApplicationNamespace } from './oauthApplication';
 import type { OrganizationResource } from './organization';
 import type { OrganizationCustomRoleKey } from './organizationMembership';
 import type { ClerkPaginationParams } from './pagination';
@@ -168,6 +169,7 @@ export type SetActiveNavigate = (params: {
  session: SessionResource;
  /**
  * Decorate the destination URL to enable Safari ITP cookie refresh when needed.
+ *
  * @see {@link DecorateUrl}
  */
  decorateUrl: DecorateUrl;
@@ -1027,6 +1029,11 @@ export interface Clerk {
  */
  apiKeys: APIKeysNamespace;
 
+ /**
+ * OAuth application helpers (e.g. consent metadata for custom consent UIs).
+ */
+ oauthApplication: OAuthApplicationNamespace;
+
  /**
  * Checkout API
  *
@@ -2496,21 +2503,25 @@ export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
  Clerk?: ClerkProp;
  /**
  * The URL that `@clerk/clerk-js` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkJSUrl?: string;
  /**
  * The npm version for `@clerk/clerk-js`.
+ *
  * @internal
  */
  __internal_clerkJSVersion?: string;
  /**
  * The URL that `@clerk/ui` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkUIUrl?: string;
  /**
  * The npm version for `@clerk/ui`.
+ *
  * @internal
  */
  __internal_clerkUIVersion?: string;

packages/shared/src/types/index.ts

@@ -33,6 +33,7 @@ export type * from './key';
 export type * from './localization';
 export type * from './multiDomain';
 export type * from './oauth';
+export type * from './oauthApplication';
 export type * from './organization';
 export type * from './organizationCreationDefaults';
 export type * from './organizationDomain';

.changeset/few-stamps-retire.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+---
+
+Add `OAuthApplication` resource and `getConsentInfo()` method for retrieving OAuth consent information, enabling custom OAuth consent flows.

packages/clerk-js/src/core/clerk.ts

@@ -88,6 +88,7 @@ import type {
  ListenerOptions,
  LoadedClerk,
  NavigateOptions,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -178,7 +179,7 @@ import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
 import { Protect } from './protect';
-import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
+import { BaseResource, Client, Environment, OAuthApplication, Organization, Waitlist } from './resources/internal';
 import { State } from './state';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -224,6 +225,7 @@ export class Clerk implements ClerkInterface {
 
  private static _billing: BillingNamespace;
  private static _apiKeys: APIKeysNamespace;
+ private static _oauthApplication: OAuthApplicationNamespace;
  private _checkout: ClerkInterface['__experimental_checkout'] | undefined;
 
  public client: ClientResource | undefined;
@@ -403,6 +405,15 @@ export class Clerk implements ClerkInterface {
  return Clerk._apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace {
+ if (!Clerk._oauthApplication) {
+ Clerk._oauthApplication = {
+ getConsentInfo: params => OAuthApplication.getConsentInfo(params),
+ };
+ }
+ return Clerk._oauthApplication;
+ }
+
  __experimental_checkout(options: __experimental_CheckoutOptions): CheckoutSignalValue {
  if (!this._checkout) {
  this._checkout = (params: any) => createCheckoutInstance(this, params);

packages/clerk-js/src/core/resources/OAuthApplication.ts

@@ -0,0 +1,49 @@
+import { ClerkRuntimeError } from '@clerk/shared/error';
+import type {
+ ClerkResourceJSON,
+ GetOAuthConsentInfoParams,
+ OAuthConsentInfo,
+ OAuthConsentInfoJSON,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class OAuthApplication extends BaseResource {
+ pathRoot = '';
+
+ protected fromJSON(_data: ClerkResourceJSON | null): this {
+ return this;
+ }
+
+ static async getConsentInfo(params: GetOAuthConsentInfoParams): Promise<OAuthConsentInfo> {
+ const { oauthClientId, scope } = params;
+ const json = await BaseResource._fetch<OAuthConsentInfoJSON>(
+ {
+ method: 'GET',
+ path: `/me/oauth/consent/${encodeURIComponent(oauthClientId)}`,
+ search: scope !== undefined ? { scope } : undefined,
+ },
+ { skipUpdateClient: true },
+ );
+
+ if (!json) {
+ throw new ClerkRuntimeError('Network request failed while offline', { code: 'network_error' });
+ }
+
+ // Handle in case we start wrapping the response in the future
+ const data = json.response ?? json;
+ return {
+ oauthApplicationName: data.oauth_application_name,
+ oauthApplicationLogoUrl: data.oauth_application_logo_url,
+ oauthApplicationUrl: data.oauth_application_url,
+ clientId: data.client_id,
+ state: data.state,
+ scopes:
+ data.scopes?.map(scope => ({
+ scope: scope.scope,
+ description: scope.description,
+ requiresConsent: scope.requires_consent,
+ })) ?? [],
+ };
+ }
+}

packages/clerk-js/src/core/resources/__tests__/OAuthApplication.test.ts

@@ -0,0 +1,149 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import type { InstanceType, OAuthConsentInfoJSON } from '@clerk/shared/types';
+import { afterEach, describe, expect, it, type Mock, vi } from 'vitest';
+
+import { mockFetch } from '@/test/core-fixtures';
+
+import { SUPPORTED_FAPI_VERSION } from '../../constants';
+import { createFapiClient } from '../../fapiClient';
+import { BaseResource } from '../internal';
+import { OAuthApplication } from '../OAuthApplication';
+
+const consentPayload: OAuthConsentInfoJSON = {
+ object: 'oauth_consent_info',
+ id: 'client_abc',
+ oauth_application_name: 'My App',
+ oauth_application_logo_url: 'https://img.example/logo.png',
+ oauth_application_url: 'https://app.example',
+ client_id: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requires_consent: true }],
+};
+
+describe('OAuthApplication.getConsentInfo', () => {
+ afterEach(() => {
+ (global.fetch as Mock)?.mockClear?.();
+ BaseResource.clerk = null as any;
+ vi.restoreAllMocks();
+ });
+
+ it('calls BaseResource._fetch with GET, encoded path, optional scope, and skipUpdateClient', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'my/client id', scope: 'openid email' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ {
+ method: 'GET',
+ path: '/me/oauth/consent/my%2Fclient%20id',
+ search: { scope: 'openid email' },
+ },
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('omits search when scope is undefined', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'cid' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ search: undefined,
+ }),
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(consentPayload as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response (enveloped)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('defaults scopes to an empty array when absent', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: { ...consentPayload, scopes: undefined },
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+ expect(info.scopes).toEqual([]);
+ });
+
+ it('maps ClerkAPIResponseError from FAPI on non-2xx', async () => {
+ mockFetch(false, 422, {
+ errors: [{ code: 'oauth_consent_error', long_message: 'Consent metadata unavailable' }],
+ });
+
+ BaseResource.clerk = {
+ getFapiClient: () =>
+ createFapiClient({
+ frontendApi: 'clerk.example.com',
+ getSessionId: () => undefined,
+ instanceType: 'development' as InstanceType,
+ }),
+ __internal_setCountry: vi.fn(),
+ handleUnauthenticated: vi.fn(),
+ __internal_handleUnauthenticatedDevBrowser: vi.fn(),
+ } as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toSatisfy(
+ (err: unknown) => err instanceof ClerkAPIResponseError && err.message === 'Consent metadata unavailable',
+ );
+
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain(`/v1/me/oauth/consent/cid`);
+ expect(url.toString()).toContain(`__clerk_api_version=${SUPPORTED_FAPI_VERSION}`);
+ });
+
+ it('throws ClerkRuntimeError when _fetch returns null (offline)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(null);
+
+ BaseResource.clerk = {} as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toMatchObject({
+ code: 'network_error',
+ });
+ });
+});

packages/clerk-js/src/core/resources/internal.ts

@@ -22,6 +22,7 @@ export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';
 export * from './Image';
+export * from './OAuthApplication';
 export * from './Organization';
 export * from './OrganizationDomain';
 export * from './OrganizationInvitation';

packages/react/src/isomorphicClerk.ts

@@ -35,6 +35,7 @@ import type {
  ListenerCallback,
  ListenerOptions,
  LoadedClerk,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -118,11 +119,13 @@ type IsomorphicLoadedClerk = Without<
  | '__internal_reloadInitialResources'
  | 'billing'
  | 'apiKeys'
+ | 'oauthApplication'
  | '__internal_setActiveInProgress'
 > & {
  client: ClientResource | undefined;
  billing: BillingNamespace | undefined;
  apiKeys: APIKeysNamespace | undefined;
+ oauthApplication: OAuthApplicationNamespace | undefined;
 };
 
 export class IsomorphicClerk implements IsomorphicLoadedClerk {
@@ -844,6 +847,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace | undefined {
+ return this.clerkjs?.oauthApplication;
+ }
+
  __experimental_checkout = (...args: Parameters<Clerk['__experimental_checkout']>) => {
  return this.loaded && this.clerkjs
  ? this.clerkjs.__experimental_checkout(...args)

packages/shared/src/types/clerk.ts

@@ -19,6 +19,7 @@ import type { DisplayThemeJSON } from './json';
 import type { LocalizationResource } from './localization';
 import type { DomainOrProxyUrl, MultiDomainAndOrProxy } from './multiDomain';
 import type { OAuthProvider, OAuthScope } from './oauth';
+import type { OAuthApplicationNamespace } from './oauthApplication';
 import type { OrganizationResource } from './organization';
 import type { OrganizationCustomRoleKey } from './organizationMembership';
 import type { ClerkPaginationParams } from './pagination';
@@ -168,6 +169,7 @@ export type SetActiveNavigate = (params: {
  session: SessionResource;
  /**
  * Decorate the destination URL to enable Safari ITP cookie refresh when needed.
+ *
  * @see {@link DecorateUrl}
  */
  decorateUrl: DecorateUrl;
@@ -1027,6 +1029,11 @@ export interface Clerk {
  */
  apiKeys: APIKeysNamespace;
 
+ /**
+ * OAuth application helpers (e.g. consent metadata for custom consent UIs).
+ */
+ oauthApplication: OAuthApplicationNamespace;
+
  /**
  * Checkout API
  *
@@ -2496,21 +2503,25 @@ export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
  Clerk?: ClerkProp;
  /**
  * The URL that `@clerk/clerk-js` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkJSUrl?: string;
  /**
  * The npm version for `@clerk/clerk-js`.
+ *
  * @internal
  */
  __internal_clerkJSVersion?: string;
  /**
  * The URL that `@clerk/ui` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkUIUrl?: string;
  /**
  * The npm version for `@clerk/ui`.
+ *
  * @internal
  */
  __internal_clerkUIVersion?: string;

packages/shared/src/types/index.ts

@@ -33,6 +33,7 @@ export type * from './key';
 export type * from './localization';
 export type * from './multiDomain';
 export type * from './oauth';
+export type * from './oauthApplication';
 export type * from './organization';
 export type * from './organizationCreationDefaults';
 export type * from './organizationDomain';

.changeset/few-stamps-retire.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+---
+
+Add `OAuthApplication` resource and `getConsentInfo()` method for retrieving OAuth consent information, enabling custom OAuth consent flows.

packages/clerk-js/src/core/clerk.ts

@@ -88,6 +88,7 @@ import type {
  ListenerOptions,
  LoadedClerk,
  NavigateOptions,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -178,7 +179,7 @@ import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
 import { Protect } from './protect';
-import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
+import { BaseResource, Client, Environment, OAuthApplication, Organization, Waitlist } from './resources/internal';
 import { State } from './state';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -224,6 +225,7 @@ export class Clerk implements ClerkInterface {
 
  private static _billing: BillingNamespace;
  private static _apiKeys: APIKeysNamespace;
+ private static _oauthApplication: OAuthApplicationNamespace;
  private _checkout: ClerkInterface['__experimental_checkout'] | undefined;
 
  public client: ClientResource | undefined;
@@ -403,6 +405,15 @@ export class Clerk implements ClerkInterface {
  return Clerk._apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace {
+ if (!Clerk._oauthApplication) {
+ Clerk._oauthApplication = {
+ getConsentInfo: params => OAuthApplication.getConsentInfo(params),
+ };
+ }
+ return Clerk._oauthApplication;
+ }
+
  __experimental_checkout(options: __experimental_CheckoutOptions): CheckoutSignalValue {
  if (!this._checkout) {
  this._checkout = (params: any) => createCheckoutInstance(this, params);

packages/clerk-js/src/core/resources/OAuthApplication.ts

@@ -0,0 +1,49 @@
+import { ClerkRuntimeError } from '@clerk/shared/error';
+import type {
+ ClerkResourceJSON,
+ GetOAuthConsentInfoParams,
+ OAuthConsentInfo,
+ OAuthConsentInfoJSON,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class OAuthApplication extends BaseResource {
+ pathRoot = '';
+
+ protected fromJSON(_data: ClerkResourceJSON | null): this {
+ return this;
+ }
+
+ static async getConsentInfo(params: GetOAuthConsentInfoParams): Promise<OAuthConsentInfo> {
+ const { oauthClientId, scope } = params;
+ const json = await BaseResource._fetch<OAuthConsentInfoJSON>(
+ {
+ method: 'GET',
+ path: `/me/oauth/consent/${encodeURIComponent(oauthClientId)}`,
+ search: scope !== undefined ? { scope } : undefined,
+ },
+ { skipUpdateClient: true },
+ );
+
+ if (!json) {
+ throw new ClerkRuntimeError('Network request failed while offline', { code: 'network_error' });
+ }
+
+ // Handle in case we start wrapping the response in the future
+ const data = json.response ?? json;
+ return {
+ oauthApplicationName: data.oauth_application_name,
+ oauthApplicationLogoUrl: data.oauth_application_logo_url,
+ oauthApplicationUrl: data.oauth_application_url,
+ clientId: data.client_id,
+ state: data.state,
+ scopes:
+ data.scopes?.map(scope => ({
+ scope: scope.scope,
+ description: scope.description,
+ requiresConsent: scope.requires_consent,
+ })) ?? [],
+ };
+ }
+}

packages/clerk-js/src/core/resources/__tests__/OAuthApplication.test.ts

@@ -0,0 +1,149 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import type { InstanceType, OAuthConsentInfoJSON } from '@clerk/shared/types';
+import { afterEach, describe, expect, it, type Mock, vi } from 'vitest';
+
+import { mockFetch } from '@/test/core-fixtures';
+
+import { SUPPORTED_FAPI_VERSION } from '../../constants';
+import { createFapiClient } from '../../fapiClient';
+import { BaseResource } from '../internal';
+import { OAuthApplication } from '../OAuthApplication';
+
+const consentPayload: OAuthConsentInfoJSON = {
+ object: 'oauth_consent_info',
+ id: 'client_abc',
+ oauth_application_name: 'My App',
+ oauth_application_logo_url: 'https://img.example/logo.png',
+ oauth_application_url: 'https://app.example',
+ client_id: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requires_consent: true }],
+};
+
+describe('OAuthApplication.getConsentInfo', () => {
+ afterEach(() => {
+ (global.fetch as Mock)?.mockClear?.();
+ BaseResource.clerk = null as any;
+ vi.restoreAllMocks();
+ });
+
+ it('calls BaseResource._fetch with GET, encoded path, optional scope, and skipUpdateClient', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'my/client id', scope: 'openid email' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ {
+ method: 'GET',
+ path: '/me/oauth/consent/my%2Fclient%20id',
+ search: { scope: 'openid email' },
+ },
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('omits search when scope is undefined', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'cid' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ search: undefined,
+ }),
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(consentPayload as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response (enveloped)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('defaults scopes to an empty array when absent', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: { ...consentPayload, scopes: undefined },
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+ expect(info.scopes).toEqual([]);
+ });
+
+ it('maps ClerkAPIResponseError from FAPI on non-2xx', async () => {
+ mockFetch(false, 422, {
+ errors: [{ code: 'oauth_consent_error', long_message: 'Consent metadata unavailable' }],
+ });
+
+ BaseResource.clerk = {
+ getFapiClient: () =>
+ createFapiClient({
+ frontendApi: 'clerk.example.com',
+ getSessionId: () => undefined,
+ instanceType: 'development' as InstanceType,
+ }),
+ __internal_setCountry: vi.fn(),
+ handleUnauthenticated: vi.fn(),
+ __internal_handleUnauthenticatedDevBrowser: vi.fn(),
+ } as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toSatisfy(
+ (err: unknown) => err instanceof ClerkAPIResponseError && err.message === 'Consent metadata unavailable',
+ );
+
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain(`/v1/me/oauth/consent/cid`);
+ expect(url.toString()).toContain(`__clerk_api_version=${SUPPORTED_FAPI_VERSION}`);
+ });
+
+ it('throws ClerkRuntimeError when _fetch returns null (offline)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(null);
+
+ BaseResource.clerk = {} as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toMatchObject({
+ code: 'network_error',
+ });
+ });
+});

packages/clerk-js/src/core/resources/internal.ts

@@ -22,6 +22,7 @@ export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';
 export * from './Image';
+export * from './OAuthApplication';
 export * from './Organization';
 export * from './OrganizationDomain';
 export * from './OrganizationInvitation';

packages/react/src/isomorphicClerk.ts

@@ -35,6 +35,7 @@ import type {
  ListenerCallback,
  ListenerOptions,
  LoadedClerk,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -118,11 +119,13 @@ type IsomorphicLoadedClerk = Without<
  | '__internal_reloadInitialResources'
  | 'billing'
  | 'apiKeys'
+ | 'oauthApplication'
  | '__internal_setActiveInProgress'
 > & {
  client: ClientResource | undefined;
  billing: BillingNamespace | undefined;
  apiKeys: APIKeysNamespace | undefined;
+ oauthApplication: OAuthApplicationNamespace | undefined;
 };
 
 export class IsomorphicClerk implements IsomorphicLoadedClerk {
@@ -844,6 +847,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace | undefined {
+ return this.clerkjs?.oauthApplication;
+ }
+
  __experimental_checkout = (...args: Parameters<Clerk['__experimental_checkout']>) => {
  return this.loaded && this.clerkjs
  ? this.clerkjs.__experimental_checkout(...args)

packages/shared/src/types/clerk.ts

@@ -19,6 +19,7 @@ import type { DisplayThemeJSON } from './json';
 import type { LocalizationResource } from './localization';
 import type { DomainOrProxyUrl, MultiDomainAndOrProxy } from './multiDomain';
 import type { OAuthProvider, OAuthScope } from './oauth';
+import type { OAuthApplicationNamespace } from './oauthApplication';
 import type { OrganizationResource } from './organization';
 import type { OrganizationCustomRoleKey } from './organizationMembership';
 import type { ClerkPaginationParams } from './pagination';
@@ -168,6 +169,7 @@ export type SetActiveNavigate = (params: {
  session: SessionResource;
  /**
  * Decorate the destination URL to enable Safari ITP cookie refresh when needed.
+ *
  * @see {@link DecorateUrl}
  */
  decorateUrl: DecorateUrl;
@@ -1027,6 +1029,11 @@ export interface Clerk {
  */
  apiKeys: APIKeysNamespace;
 
+ /**
+ * OAuth application helpers (e.g. consent metadata for custom consent UIs).
+ */
+ oauthApplication: OAuthApplicationNamespace;
+
  /**
  * Checkout API
  *
@@ -2496,21 +2503,25 @@ export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
  Clerk?: ClerkProp;
  /**
  * The URL that `@clerk/clerk-js` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkJSUrl?: string;
  /**
  * The npm version for `@clerk/clerk-js`.
+ *
  * @internal
  */
  __internal_clerkJSVersion?: string;
  /**
  * The URL that `@clerk/ui` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkUIUrl?: string;
  /**
  * The npm version for `@clerk/ui`.
+ *
  * @internal
  */
  __internal_clerkUIVersion?: string;

packages/shared/src/types/index.ts

@@ -33,6 +33,7 @@ export type * from './key';
 export type * from './localization';
 export type * from './multiDomain';
 export type * from './oauth';
+export type * from './oauthApplication';
 export type * from './organization';
 export type * from './organizationCreationDefaults';
 export type * from './organizationDomain';

.changeset/few-stamps-retire.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+---
+
+Add `OAuthApplication` resource and `getConsentInfo()` method for retrieving OAuth consent information, enabling custom OAuth consent flows.

packages/clerk-js/src/core/clerk.ts

@@ -88,6 +88,7 @@ import type {
  ListenerOptions,
  LoadedClerk,
  NavigateOptions,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -178,7 +179,7 @@ import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
 import { Protect } from './protect';
-import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
+import { BaseResource, Client, Environment, OAuthApplication, Organization, Waitlist } from './resources/internal';
 import { State } from './state';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -224,6 +225,7 @@ export class Clerk implements ClerkInterface {
 
  private static _billing: BillingNamespace;
  private static _apiKeys: APIKeysNamespace;
+ private static _oauthApplication: OAuthApplicationNamespace;
  private _checkout: ClerkInterface['__experimental_checkout'] | undefined;
 
  public client: ClientResource | undefined;
@@ -403,6 +405,15 @@ export class Clerk implements ClerkInterface {
  return Clerk._apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace {
+ if (!Clerk._oauthApplication) {
+ Clerk._oauthApplication = {
+ getConsentInfo: params => OAuthApplication.getConsentInfo(params),
+ };
+ }
+ return Clerk._oauthApplication;
+ }
+
  __experimental_checkout(options: __experimental_CheckoutOptions): CheckoutSignalValue {
  if (!this._checkout) {
  this._checkout = (params: any) => createCheckoutInstance(this, params);

packages/clerk-js/src/core/resources/OAuthApplication.ts

@@ -0,0 +1,49 @@
+import { ClerkRuntimeError } from '@clerk/shared/error';
+import type {
+ ClerkResourceJSON,
+ GetOAuthConsentInfoParams,
+ OAuthConsentInfo,
+ OAuthConsentInfoJSON,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class OAuthApplication extends BaseResource {
+ pathRoot = '';
+
+ protected fromJSON(_data: ClerkResourceJSON | null): this {
+ return this;
+ }
+
+ static async getConsentInfo(params: GetOAuthConsentInfoParams): Promise<OAuthConsentInfo> {
+ const { oauthClientId, scope } = params;
+ const json = await BaseResource._fetch<OAuthConsentInfoJSON>(
+ {
+ method: 'GET',
+ path: `/me/oauth/consent/${encodeURIComponent(oauthClientId)}`,
+ search: scope !== undefined ? { scope } : undefined,
+ },
+ { skipUpdateClient: true },
+ );
+
+ if (!json) {
+ throw new ClerkRuntimeError('Network request failed while offline', { code: 'network_error' });
+ }
+
+ // Handle in case we start wrapping the response in the future
+ const data = json.response ?? json;
+ return {
+ oauthApplicationName: data.oauth_application_name,
+ oauthApplicationLogoUrl: data.oauth_application_logo_url,
+ oauthApplicationUrl: data.oauth_application_url,
+ clientId: data.client_id,
+ state: data.state,
+ scopes:
+ data.scopes?.map(scope => ({
+ scope: scope.scope,
+ description: scope.description,
+ requiresConsent: scope.requires_consent,
+ })) ?? [],
+ };
+ }
+}

packages/clerk-js/src/core/resources/__tests__/OAuthApplication.test.ts

@@ -0,0 +1,149 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import type { InstanceType, OAuthConsentInfoJSON } from '@clerk/shared/types';
+import { afterEach, describe, expect, it, type Mock, vi } from 'vitest';
+
+import { mockFetch } from '@/test/core-fixtures';
+
+import { SUPPORTED_FAPI_VERSION } from '../../constants';
+import { createFapiClient } from '../../fapiClient';
+import { BaseResource } from '../internal';
+import { OAuthApplication } from '../OAuthApplication';
+
+const consentPayload: OAuthConsentInfoJSON = {
+ object: 'oauth_consent_info',
+ id: 'client_abc',
+ oauth_application_name: 'My App',
+ oauth_application_logo_url: 'https://img.example/logo.png',
+ oauth_application_url: 'https://app.example',
+ client_id: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requires_consent: true }],
+};
+
+describe('OAuthApplication.getConsentInfo', () => {
+ afterEach(() => {
+ (global.fetch as Mock)?.mockClear?.();
+ BaseResource.clerk = null as any;
+ vi.restoreAllMocks();
+ });
+
+ it('calls BaseResource._fetch with GET, encoded path, optional scope, and skipUpdateClient', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'my/client id', scope: 'openid email' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ {
+ method: 'GET',
+ path: '/me/oauth/consent/my%2Fclient%20id',
+ search: { scope: 'openid email' },
+ },
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('omits search when scope is undefined', async () => {
+ const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ await OAuthApplication.getConsentInfo({ oauthClientId: 'cid' });
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ search: undefined,
+ }),
+ { skipUpdateClient: true },
+ );
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(consentPayload as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('returns OAuthConsentInfo from the FAPI response (enveloped)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: consentPayload,
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+
+ expect(info).toEqual({
+ oauthApplicationName: 'My App',
+ oauthApplicationLogoUrl: 'https://img.example/logo.png',
+ oauthApplicationUrl: 'https://app.example',
+ clientId: 'client_abc',
+ state: 'st',
+ scopes: [{ scope: 'openid', description: 'OpenID', requiresConsent: true }],
+ });
+ });
+
+ it('defaults scopes to an empty array when absent', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+ response: { ...consentPayload, scopes: undefined },
+ } as any);
+
+ BaseResource.clerk = {} as any;
+
+ const info = await OAuthApplication.getConsentInfo({ oauthClientId: 'client_abc' });
+ expect(info.scopes).toEqual([]);
+ });
+
+ it('maps ClerkAPIResponseError from FAPI on non-2xx', async () => {
+ mockFetch(false, 422, {
+ errors: [{ code: 'oauth_consent_error', long_message: 'Consent metadata unavailable' }],
+ });
+
+ BaseResource.clerk = {
+ getFapiClient: () =>
+ createFapiClient({
+ frontendApi: 'clerk.example.com',
+ getSessionId: () => undefined,
+ instanceType: 'development' as InstanceType,
+ }),
+ __internal_setCountry: vi.fn(),
+ handleUnauthenticated: vi.fn(),
+ __internal_handleUnauthenticatedDevBrowser: vi.fn(),
+ } as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toSatisfy(
+ (err: unknown) => err instanceof ClerkAPIResponseError && err.message === 'Consent metadata unavailable',
+ );
+
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain(`/v1/me/oauth/consent/cid`);
+ expect(url.toString()).toContain(`__clerk_api_version=${SUPPORTED_FAPI_VERSION}`);
+ });
+
+ it('throws ClerkRuntimeError when _fetch returns null (offline)', async () => {
+ vi.spyOn(BaseResource, '_fetch').mockResolvedValue(null);
+
+ BaseResource.clerk = {} as any;
+
+ await expect(OAuthApplication.getConsentInfo({ oauthClientId: 'cid' })).rejects.toMatchObject({
+ code: 'network_error',
+ });
+ });
+});

packages/clerk-js/src/core/resources/internal.ts

@@ -22,6 +22,7 @@ export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';
 export * from './Image';
+export * from './OAuthApplication';
 export * from './Organization';
 export * from './OrganizationDomain';
 export * from './OrganizationInvitation';

packages/react/src/isomorphicClerk.ts

@@ -35,6 +35,7 @@ import type {
  ListenerCallback,
  ListenerOptions,
  LoadedClerk,
+ OAuthApplicationNamespace,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -118,11 +119,13 @@ type IsomorphicLoadedClerk = Without<
  | '__internal_reloadInitialResources'
  | 'billing'
  | 'apiKeys'
+ | 'oauthApplication'
  | '__internal_setActiveInProgress'
 > & {
  client: ClientResource | undefined;
  billing: BillingNamespace | undefined;
  apiKeys: APIKeysNamespace | undefined;
+ oauthApplication: OAuthApplicationNamespace | undefined;
 };
 
 export class IsomorphicClerk implements IsomorphicLoadedClerk {
@@ -844,6 +847,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.apiKeys;
  }
 
+ get oauthApplication(): OAuthApplicationNamespace | undefined {
+ return this.clerkjs?.oauthApplication;
+ }
+
  __experimental_checkout = (...args: Parameters<Clerk['__experimental_checkout']>) => {
  return this.loaded && this.clerkjs
  ? this.clerkjs.__experimental_checkout(...args)

packages/shared/src/types/clerk.ts

@@ -19,6 +19,7 @@ import type { DisplayThemeJSON } from './json';
 import type { LocalizationResource } from './localization';
 import type { DomainOrProxyUrl, MultiDomainAndOrProxy } from './multiDomain';
 import type { OAuthProvider, OAuthScope } from './oauth';
+import type { OAuthApplicationNamespace } from './oauthApplication';
 import type { OrganizationResource } from './organization';
 import type { OrganizationCustomRoleKey } from './organizationMembership';
 import type { ClerkPaginationParams } from './pagination';
@@ -168,6 +169,7 @@ export type SetActiveNavigate = (params: {
  session: SessionResource;
  /**
  * Decorate the destination URL to enable Safari ITP cookie refresh when needed.
+ *
  * @see {@link DecorateUrl}
  */
  decorateUrl: DecorateUrl;
@@ -1027,6 +1029,11 @@ export interface Clerk {
  */
  apiKeys: APIKeysNamespace;
 
+ /**
+ * OAuth application helpers (e.g. consent metadata for custom consent UIs).
+ */
+ oauthApplication: OAuthApplicationNamespace;
+
  /**
  * Checkout API
  *
@@ -2496,21 +2503,25 @@ export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
  Clerk?: ClerkProp;
  /**
  * The URL that `@clerk/clerk-js` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkJSUrl?: string;
  /**
  * The npm version for `@clerk/clerk-js`.
+ *
  * @internal
  */
  __internal_clerkJSVersion?: string;
  /**
  * The URL that `@clerk/ui` should be hot-loaded from.
+ *
  * @internal
  */
  __internal_clerkUIUrl?: string;
  /**
  * The npm version for `@clerk/ui`.
+ *
  * @internal
  */
  __internal_clerkUIVersion?: string;

packages/shared/src/types/index.ts

@@ -33,6 +33,7 @@ export type * from './key';
 export type * from './localization';
 export type * from './multiDomain';
 export type * from './oauth';
+export type * from './oauthApplication';
 export type * from './organization';
 export type * from './organizationCreationDefaults';
 export type * from './organizationDomain';