;
+};
+
+const normalizeUserCode = (userCode: string) => userCode.toUpperCase().replace(/[-\p{White_Space}]/gu, '');
+
+const createNotReadyError = () =>
+ new ClerkRuntimeError('Clerk must be loaded before using OAuth device verification.', {
+ code: 'oauth_device_verification_not_ready',
+ });
+
+const createLookupInProgressError = () =>
+ new ClerkRuntimeError('An OAuth device verification lookup is already in progress for another code.', {
+ code: 'oauth_device_verification_lookup_in_progress',
+ });
+
+const createSubmissionInProgressError = () =>
+ new ClerkRuntimeError('Another OAuth device verification decision is already in progress.', {
+ code: 'oauth_device_verification_submission_in_progress',
+ });
+
+/**
+ * Provides state and actions for building a custom OAuth device verification flow.
+ *
+ * @returns The current verification state and methods for looking up, approving, denying, or resetting a request.
+ *
+ * @example
+ * ### Look up a device authorization request
+ *
+ * ```tsx
+ * import { useOAuthDeviceVerification } from '@clerk/react';
+ *
+ * function CustomDeviceVerification({ userCode }: { userCode: string }) {
+ * const { data, isLoading, lookup } = useOAuthDeviceVerification();
+ *
+ * const handleLookup = async () => {
+ * await lookup({ userCode });
+ * };
+ *
+ * return (
+ * <>
+ *
+ * {data && Authorize {data.oauthApplicationName}?
}
+ *
+ * );
+ * }
+ * ```
+ */
+export function useOAuthDeviceVerification(): UseOAuthDeviceVerificationReturn {
+ useAssertWrappedByClerkProvider(HOOK_NAME);
+ const clerk = useClerkInstanceContext();
+ const [data, setData] = useState();
+ const [result, setResult] = useState();
+ const [error, setError] = useState(null);
+ const [isLoading, setIsLoading] = useState(false);
+ const [isSubmitting, setIsSubmitting] = useState(false);
+ const pendingLookup = useRef(null);
+ const pendingSubmit = useRef(null);
+ const generation = useRef(0);
+
+ clerk.telemetry?.record(eventMethodCalled(HOOK_NAME));
+
+ const lookup = useCallback(
+ (params: LookupOAuthDeviceVerificationParams) => {
+ const oauthApplication = clerk.loaded ? clerk.oauthApplication : undefined;
+ if (!oauthApplication) {
+ return Promise.reject(createNotReadyError());
+ }
+
+ const key = normalizeUserCode(params.userCode);
+ if (pendingLookup.current) {
+ if (pendingLookup.current.key === key) {
+ return pendingLookup.current.promise;
+ }
+ return Promise.reject(createLookupInProgressError());
+ }
+
+ const requestGeneration = generation.current;
+ setError(null);
+ setData(undefined);
+ setResult(undefined);
+ setIsLoading(true);
+
+ const request = oauthApplication
+ .lookupDeviceVerification({ ...params, userCode: key })
+ .then(info => {
+ if (generation.current === requestGeneration) {
+ setData(info);
+ }
+ return info;
+ })
+ .catch((err: HookError) => {
+ if (generation.current === requestGeneration) {
+ setError(err);
+ }
+ throw err;
+ })
+ .finally(() => {
+ if (pendingLookup.current?.promise === request) {
+ pendingLookup.current = null;
+ }
+ if (generation.current === requestGeneration) {
+ setIsLoading(false);
+ }
+ });
+
+ pendingLookup.current = { key, promise: request };
+ return request;
+ },
+ [clerk],
+ );
+
+ const submit = useCallback(
+ (params: DecisionParams, approved: boolean) => {
+ const oauthApplication = clerk.loaded ? clerk.oauthApplication : undefined;
+ if (!oauthApplication) {
+ return Promise.reject(createNotReadyError());
+ }
+
+ const userCode = normalizeUserCode(params.userCode);
+ const key = JSON.stringify([userCode, params.organizationId ?? null, approved]);
+ if (pendingSubmit.current) {
+ if (pendingSubmit.current.key === key) {
+ return pendingSubmit.current.promise;
+ }
+ return Promise.reject(createSubmissionInProgressError());
+ }
+
+ const requestGeneration = generation.current;
+ setError(null);
+ setIsSubmitting(true);
+
+ const request = oauthApplication
+ .submitDeviceVerification({ ...params, userCode, approved })
+ .then(decision => {
+ if (generation.current === requestGeneration) {
+ setResult(decision);
+ }
+ return decision;
+ })
+ .catch((err: HookError) => {
+ if (generation.current === requestGeneration) {
+ setError(err);
+ }
+ throw err;
+ })
+ .finally(() => {
+ if (pendingSubmit.current?.promise === request) {
+ pendingSubmit.current = null;
+ }
+ if (generation.current === requestGeneration) {
+ setIsSubmitting(false);
+ }
+ });
+
+ pendingSubmit.current = { key, promise: request };
+ return request;
+ },
+ [clerk],
+ );
+
+ const approve = useCallback((params: DecisionParams) => submit(params, true), [submit]);
+ const deny = useCallback((params: LookupOAuthDeviceVerificationParams) => submit(params, false), [submit]);
+
+ const reset = useCallback(() => {
+ generation.current += 1;
+ pendingLookup.current = null;
+ setData(undefined);
+ setResult(undefined);
+ setError(null);
+ setIsLoading(false);
+ setIsSubmitting(false);
+ }, []);
+
+ return { data, result, error, isLoading, isSubmitting, lookup, approve, deny, reset };
+}
diff --git a/packages/shared/src/react/hooks/useOAuthDeviceVerification.types.ts b/packages/shared/src/react/hooks/useOAuthDeviceVerification.types.ts
new file mode 100644
index 00000000000..9b223a58caf
--- /dev/null
+++ b/packages/shared/src/react/hooks/useOAuthDeviceVerification.types.ts
@@ -0,0 +1,22 @@
+import type { ClerkAPIResponseError } from '../../errors/clerkApiResponseError';
+import type { ClerkRuntimeError } from '../../errors/clerkRuntimeError';
+import type {
+ LookupOAuthDeviceVerificationParams,
+ OAuthDeviceVerificationInfo,
+ OAuthDeviceVerificationResult,
+ SubmitOAuthDeviceVerificationParams,
+} from '../../types';
+
+type DecisionParams = Omit;
+
+export type UseOAuthDeviceVerificationReturn = {
+ data: OAuthDeviceVerificationInfo | undefined;
+ result: OAuthDeviceVerificationResult | undefined;
+ error: ClerkAPIResponseError | ClerkRuntimeError | null;
+ isLoading: boolean;
+ isSubmitting: boolean;
+ lookup: (params: LookupOAuthDeviceVerificationParams) => Promise;
+ approve: (params: DecisionParams) => Promise;
+ deny: (params: LookupOAuthDeviceVerificationParams) => Promise;
+ reset: () => void;
+};
diff --git a/packages/shared/src/types/clerk.ts b/packages/shared/src/types/clerk.ts
index 0f57591517d..bf5325b7e62 100644
--- a/packages/shared/src/types/clerk.ts
+++ b/packages/shared/src/types/clerk.ts
@@ -848,6 +848,23 @@ export interface Clerk {
*/
unmountOAuthConsent: (targetNode: HTMLDivElement) => void;
+ /**
+ * Mounts an OAuth device verification component at the target element.
+ *
+ * @param targetNode - Target node to mount the OAuth device verification component.
+ * @param props - OAuth device verification configuration parameters.
+ * @internal
+ */
+ __internal_mountOAuthDeviceVerification: (targetNode: HTMLDivElement, props?: OAuthDeviceVerificationProps) => void;
+
+ /**
+ * Unmounts an OAuth device verification component from the target element.
+ * If there is no component mounted at the target node, this is a noop.
+ *
+ * @internal
+ */
+ __internal_unmountOAuthDeviceVerification: (targetNode: HTMLDivElement) => void;
+
/**
* Mounts a TaskChooseOrganization component at the target element.
*
@@ -2770,6 +2787,13 @@ export type OAuthConsentProps = {
onDeny?: () => void;
};
+export type OAuthDeviceVerificationProps = {
+ /**
+ * Customization options to fully match the Clerk component to your own brand.
+ */
+ appearance?: ClerkAppearanceTheme;
+};
+
/** @deprecated Use OAuthConsentProps instead. */
export type __internal_OAuthConsentProps = OAuthConsentProps;
diff --git a/packages/shared/src/types/elementIds.ts b/packages/shared/src/types/elementIds.ts
index 6975892a769..03a51460dc5 100644
--- a/packages/shared/src/types/elementIds.ts
+++ b/packages/shared/src/types/elementIds.ts
@@ -15,6 +15,7 @@ export type FieldId =
| 'identifier'
| 'username'
| 'code'
+ | 'userCode'
| 'role'
| 'deleteConfirmation'
| 'deleteOrganizationConfirmation'
diff --git a/packages/shared/src/types/localization.ts b/packages/shared/src/types/localization.ts
index 82c326a2248..f1f6e9dd7bf 100644
--- a/packages/shared/src/types/localization.ts
+++ b/packages/shared/src/types/localization.ts
@@ -1374,6 +1374,47 @@ export type __internal_LocalizationResource = {
subtitle: LocalizationValue<'applicationName'>;
};
};
+ oauthDeviceVerification: {
+ start: {
+ title: LocalizationValue;
+ subtitle: LocalizationValue;
+ userCodeLabel: LocalizationValue;
+ action__continue: LocalizationValue;
+ };
+ confirmation: {
+ title: LocalizationValue<'applicationName'>;
+ subtitle: LocalizationValue<'identifier'>;
+ scopeListTitle: LocalizationValue<'applicationName'>;
+ warning: LocalizationValue;
+ action__deny: LocalizationValue;
+ action__approve: LocalizationValue;
+ };
+ status: {
+ approvedTitle: LocalizationValue;
+ approvedSubtitle: LocalizationValue;
+ alreadyApprovedTitle: LocalizationValue;
+ alreadyApprovedSubtitle: LocalizationValue;
+ alreadyDecidedTitle: LocalizationValue;
+ alreadyDecidedSubtitle: LocalizationValue;
+ deniedTitle: LocalizationValue;
+ deniedSubtitle: LocalizationValue;
+ alreadyDeniedTitle: LocalizationValue;
+ alreadyDeniedSubtitle: LocalizationValue;
+ consumedTitle: LocalizationValue;
+ consumedSubtitle: LocalizationValue;
+ };
+ error: {
+ invalidCode: LocalizationValue;
+ unknownCode: LocalizationValue;
+ expiredTitle: LocalizationValue;
+ expiredSubtitle: LocalizationValue;
+ rateLimitedTitle: LocalizationValue;
+ rateLimitedSubtitle: LocalizationValue;
+ genericTitle: LocalizationValue;
+ genericSubtitle: LocalizationValue;
+ };
+ action__tryAnotherCode: LocalizationValue;
+ };
unstable__errors: UnstableErrors;
dates: {
previous6Days: LocalizationValue<'date'>;
diff --git a/packages/shared/src/types/oauthApplication.ts b/packages/shared/src/types/oauthApplication.ts
index 3d633999e72..584c976bc65 100644
--- a/packages/shared/src/types/oauthApplication.ts
+++ b/packages/shared/src/types/oauthApplication.ts
@@ -9,6 +9,26 @@ export type OAuthConsentScopeJSON = {
requires_consent: boolean;
};
+/**
+ * @internal
+ */
+export type OAuthDeviceVerificationInfoJSON = {
+ oauth_application_name: string;
+ oauth_application_logo_url: string | null;
+ client_id: string;
+ scopes: OAuthConsentScopeJSON[];
+ status: OAuthDeviceVerificationStatus;
+ expires_at: number;
+};
+
+/**
+ * @internal
+ */
+export type OAuthDeviceVerificationResultJSON = {
+ object: 'oauth_device_verification';
+ status: Extract;
+};
+
/**
* @internal
*/
@@ -81,6 +101,34 @@ export type OAuthConsentInfo = {
scopes: OAuthConsentScope[];
};
+export type OAuthDeviceVerificationStatus = 'pending' | 'approved' | 'denied' | 'consumed';
+
+/**
+ * A scope requested by an OAuth device authorization.
+ */
+export type OAuthDeviceVerificationScope = OAuthConsentScope;
+
+/**
+ * Information about an OAuth device authorization awaiting verification.
+ */
+export type OAuthDeviceVerificationInfo = {
+ oauthApplicationName: string;
+ oauthApplicationLogoUrl: string | null;
+ clientId: string;
+ scopes: OAuthDeviceVerificationScope[];
+ status: OAuthDeviceVerificationStatus;
+ /** Expiration time as Unix milliseconds. */
+ expiresAt: number;
+};
+
+/**
+ * The result of approving or denying an OAuth device authorization.
+ */
+export type OAuthDeviceVerificationResult = {
+ object: 'oauth_device_verification';
+ status: Extract;
+};
+
export type GetOAuthConsentInfoParams = {
/** The OAuth `client_id` from the authorize request. The hook is disabled when this value is empty or omitted. */
oauthClientId: string;
@@ -90,6 +138,16 @@ export type GetOAuthConsentInfoParams = {
redirectUri?: string;
};
+export type LookupOAuthDeviceVerificationParams = {
+ userCode: string;
+};
+
+export type SubmitOAuthDeviceVerificationParams = {
+ userCode: string;
+ approved: boolean;
+ organizationId?: string;
+};
+
/**
* Namespace exposed on `Clerk` for OAuth application / consent helpers.
*/
@@ -99,6 +157,16 @@ export interface OAuthApplicationNamespace {
*/
getConsentInfo: (params: GetOAuthConsentInfoParams) => Promise;
+ /**
+ * Looks up an OAuth device authorization by its human-readable user code.
+ */
+ lookupDeviceVerification: (params: LookupOAuthDeviceVerificationParams) => Promise;
+
+ /**
+ * Approves or denies an OAuth device authorization for the signed-in user.
+ */
+ submitDeviceVerification: (params: SubmitOAuthDeviceVerificationParams) => Promise;
+
/**
* Returns the URL to use as the `action` attribute of the consent form.
* Includes `_clerk_session_id` and, in development, the dev browser JWT.
diff --git a/packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap
index ee11ac03e0f..bc8dc12e555 100644
--- a/packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap
+++ b/packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -34,6 +34,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
"HandleSSOCallback",
"InviteMembersButton",
"OAuthConsent",
+ "OAuthDeviceVerification",
"OrganizationList",
"OrganizationProfile",
"OrganizationSwitcher",
@@ -70,6 +71,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
"useClerk",
"useEmailLink",
"useOAuthConsent",
+ "useOAuthDeviceVerification",
"useOrganization",
"useOrganizationCreationDefaults",
"useOrganizationList",
diff --git a/packages/ui/bundlewatch.config.json b/packages/ui/bundlewatch.config.json
index 4206be9da18..e8ac59cbbfd 100644
--- a/packages/ui/bundlewatch.config.json
+++ b/packages/ui/bundlewatch.config.json
@@ -27,6 +27,7 @@
{ "path": "./dist/subscriptionDetails*.js", "maxSize": "7KB" },
{ "path": "./dist/apiKeys*.js", "maxSize": "6KB" },
{ "path": "./dist/oauthConsent*.js", "maxSize": "7.5KB" },
+ { "path": "./dist/oauthDeviceVerification*.js", "maxSize": "5.5KB" },
{ "path": "./dist/up-billing-page*.js", "maxSize": "3KB" },
{ "path": "./dist/op-billing-page*.js", "maxSize": "3KB" },
{ "path": "./dist/up-plans-page*.js", "maxSize": "2.5KB" },
diff --git a/packages/ui/src/components/OAuthDeviceVerification/OAuthDeviceVerification.tsx b/packages/ui/src/components/OAuthDeviceVerification/OAuthDeviceVerification.tsx
new file mode 100644
index 00000000000..bda29d436b3
--- /dev/null
+++ b/packages/ui/src/components/OAuthDeviceVerification/OAuthDeviceVerification.tsx
@@ -0,0 +1,523 @@
+import { isClerkAPIResponseError } from '@clerk/shared/error';
+import { useClerk, useOAuthDeviceVerification, useUser } from '@clerk/shared/react';
+import type { OAuthDeviceVerificationInfo } from '@clerk/shared/types';
+import type { FormEventHandler } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { useEnvironment, withCoreUserGuard } from '@/ui/contexts';
+import { Button, Col, Flow, Grid, Image, localizationKeys, Text, useLocalizations } from '@/ui/customizables';
+import { ApplicationLogo } from '@/ui/elements/ApplicationLogo';
+import { Card } from '@/ui/elements/Card';
+import { withCardStateProvider } from '@/ui/elements/contexts';
+import { Form } from '@/ui/elements/Form';
+import { Header } from '@/ui/elements/Header';
+import { LoadingCardContainer } from '@/ui/elements/LoadingCard';
+import { Alert } from '@/ui/primitives';
+import { Route, Switch } from '@/ui/router';
+import { useFormControl } from '@/ui/utils/useFormControl';
+
+import {
+ ListGroup,
+ ListGroupContent,
+ ListGroupHeader,
+ ListGroupHeaderTitle,
+ ListGroupItem,
+ ListGroupItemLabel,
+} from '../OAuthConsent/ListGroup';
+import {
+ LogoGroup,
+ LogoGroupIcon,
+ LogoGroupItem,
+ LogoGroupItemContainer,
+ LogoGroupSeparator,
+} from '../OAuthConsent/LogoGroup';
+import { OrgSelect } from '../OAuthConsent/OrgSelect';
+import { OAuthDeviceVerificationCodeInput } from './OAuthDeviceVerificationCodeInput';
+import { getOAuthDeviceUserCodeFromSearch, isValidOAuthDeviceUserCode, normalizeOAuthDeviceUserCode } from './utils';
+
+const USER_ORG_READ_SCOPE = 'user:org:read';
+const OFFLINE_ACCESS_SCOPE = 'offline_access';
+const PRIVATE_METADATA_SCOPE = 'private_metadata';
+
+type View =
+ | 'entry'
+ | 'loading'
+ | 'confirmation'
+ | 'approved'
+ | 'alreadyApproved'
+ | 'denied'
+ | 'alreadyDenied'
+ | 'consumed'
+ | 'expired'
+ | 'rateLimited'
+ | 'alreadyDecided'
+ | 'error';
+
+function getErrorCode(error: unknown): string | undefined {
+ return isClerkAPIResponseError(error) ? error.errors?.[0]?.code : undefined;
+}
+
+function OAuthDeviceVerificationInternal() {
+ const clerk = useClerk();
+ const { user } = useUser();
+ const {
+ displayConfig: { applicationName, logoImageUrl },
+ organizationSettings,
+ } = useEnvironment();
+ const { t } = useLocalizations();
+ const verification = useOAuthDeviceVerification();
+ const [view, setView] = useState('entry');
+ const [selectedOrg, setSelectedOrg] = useState(null);
+ const [submittingDecision, setSubmittingDecision] = useState<'approve' | 'deny' | null>(null);
+ const handledPrefill = useRef(false);
+ const decisionInProgress = useRef(false);
+
+ const codeControl = useFormControl('userCode', '', {
+ type: 'text',
+ label: localizationKeys('oauthDeviceVerification.start.userCodeLabel'),
+ transformer: normalizeOAuthDeviceUserCode,
+ isRequired: true,
+ });
+
+ const showLookupError = useCallback(
+ (error: unknown) => {
+ switch (getErrorCode(error)) {
+ case 'resource_not_found':
+ setView('entry');
+ codeControl.setError(t(localizationKeys('oauthDeviceVerification.error.unknownCode')));
+ break;
+ case 'oauth_device_code_expired':
+ setView('expired');
+ break;
+ case 'too_many_requests':
+ setView('rateLimited');
+ break;
+ default:
+ setView('error');
+ }
+ },
+ [codeControl, t],
+ );
+
+ const showLookupResult = useCallback((info: OAuthDeviceVerificationInfo) => {
+ switch (info.status) {
+ case 'pending':
+ setView('confirmation');
+ break;
+ case 'approved':
+ setView('alreadyApproved');
+ break;
+ case 'denied':
+ setView('alreadyDenied');
+ break;
+ case 'consumed':
+ setView('consumed');
+ break;
+ default:
+ setView('error');
+ }
+ }, []);
+
+ const lookup = useCallback(
+ async (userCode: string) => {
+ codeControl.clearFeedback();
+ setView('loading');
+ try {
+ const info = await verification.lookup({ userCode });
+ showLookupResult(info);
+ } catch (error) {
+ showLookupError(error);
+ }
+ },
+ [codeControl, showLookupError, showLookupResult, verification],
+ );
+
+ useEffect(() => {
+ if (handledPrefill.current) {
+ return;
+ }
+ handledPrefill.current = true;
+
+ const userCode = getOAuthDeviceUserCodeFromSearch();
+ if (!userCode) {
+ return;
+ }
+
+ codeControl.setValue(normalizeOAuthDeviceUserCode(userCode));
+ if (!isValidOAuthDeviceUserCode(userCode)) {
+ codeControl.setError(t(localizationKeys('oauthDeviceVerification.error.invalidCode')));
+ return;
+ }
+
+ void lookup(normalizeOAuthDeviceUserCode(userCode));
+ }, [codeControl, lookup, t]);
+
+ const handleLookup: FormEventHandler = event => {
+ event.preventDefault();
+ const userCode = normalizeOAuthDeviceUserCode(codeControl.value);
+ if (!isValidOAuthDeviceUserCode(userCode)) {
+ codeControl.setError(t(localizationKeys('oauthDeviceVerification.error.invalidCode')));
+ return;
+ }
+ void lookup(userCode);
+ };
+
+ const data = verification.data;
+ const hasOrgReadScope = data?.scopes.some(scope => scope.scope === USER_ORG_READ_SCOPE) ?? false;
+ const orgSelectionEnabled = hasOrgReadScope && organizationSettings.enabled;
+ const orgOptions = orgSelectionEnabled
+ ? (user?.organizationMemberships ?? []).map(membership => ({
+ value: membership.organization.id,
+ label: membership.organization.name,
+ logoUrl: membership.organization.imageUrl,
+ }))
+ : [];
+ const lastActiveOrgId = clerk.session?.lastActiveOrganizationId;
+ const defaultOrg = orgOptions.find(option => option.value === lastActiveOrgId)?.value ?? orgOptions[0]?.value ?? null;
+ const effectiveOrg = selectedOrg ?? defaultOrg;
+
+ const showDecisionError = (error: unknown) => {
+ switch (getErrorCode(error)) {
+ case 'oauth_device_code_expired':
+ setView('expired');
+ break;
+ case 'too_many_requests':
+ setView('rateLimited');
+ break;
+ case 'bad_request':
+ setView('alreadyDecided');
+ break;
+ default:
+ setView('error');
+ }
+ };
+
+ const handleApprove = async () => {
+ if (decisionInProgress.current) {
+ return;
+ }
+ decisionInProgress.current = true;
+ const userCode = normalizeOAuthDeviceUserCode(codeControl.value);
+ setSubmittingDecision('approve');
+ try {
+ await verification.approve({ userCode, organizationId: effectiveOrg ?? undefined });
+ setView('approved');
+ } catch (error) {
+ showDecisionError(error);
+ } finally {
+ decisionInProgress.current = false;
+ setSubmittingDecision(null);
+ }
+ };
+
+ const handleDeny = async () => {
+ if (decisionInProgress.current) {
+ return;
+ }
+ decisionInProgress.current = true;
+ const userCode = normalizeOAuthDeviceUserCode(codeControl.value);
+ setSubmittingDecision('deny');
+ try {
+ await verification.deny({ userCode });
+ setView('denied');
+ } catch (error) {
+ showDecisionError(error);
+ } finally {
+ decisionInProgress.current = false;
+ setSubmittingDecision(null);
+ }
+ };
+
+ const reset = () => {
+ decisionInProgress.current = false;
+ verification.reset();
+ codeControl.setValue('');
+ codeControl.clearFeedback();
+ setSelectedOrg(null);
+ setView('entry');
+ };
+
+ if (view === 'loading') {
+ return (
+
+
+
+
+
+
+ );
+ }
+
+ if (view === 'entry') {
+ return (
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+ }
+
+ if (view === 'confirmation' && data) {
+ const primaryIdentifier = user?.primaryEmailAddress?.emailAddress || user?.primaryPhoneNumber?.phoneNumber || '';
+ const displayedScopes = data.scopes
+ .filter(scope => scope.scope !== OFFLINE_ACCESS_SCOPE)
+ .map(scope => ({
+ ...scope,
+ description:
+ scope.scope === PRIVATE_METADATA_SCOPE
+ ? t(
+ localizationKeys('oauthConsent.scopeList.privateMetadata', {
+ applicationName,
+ }),
+ )
+ : scope.description,
+ }));
+ const hasOfflineAccess = data.scopes.some(scope => scope.scope === OFFLINE_ACCESS_SCOPE);
+ return (
+
+
+
+
+
+
+
+ {orgSelectionEnabled && orgOptions.length > 0 && effectiveOrg && (
+
+ )}
+
+
+
+
+
+ {displayedScopes.map(scope => (
+
+ {scope.description || scope.scope}
+
+ ))}
+
+
+
+
+
+
+
+
+
+
+ );
+ }
+
+ if (view === 'confirmation') {
+ return (
+
+
+
+
+
+
+ );
+ }
+
+ const terminal = getTerminalContent(view);
+ return (
+
+
+
+
+
+
+
+ {terminal.canReset && (
+
+ )}
+
+
+
+
+ );
+}
+
+function DeviceLogo({
+ applicationName,
+ logoUrl,
+ showClerkLogo,
+}: {
+ applicationName: string;
+ logoUrl: string | null;
+ showClerkLogo: boolean;
+}) {
+ const applicationMark = logoUrl ? (
+
+ ) : (
+
+ );
+
+ if (!showClerkLogo) {
+ return (
+
+ {applicationMark}
+
+ );
+ }
+
+ return (
+
+
+ {applicationMark}
+
+
+
+
+
+
+
+
+ );
+}
+
+function getTerminalContent(view: Exclude): {
+ title: Parameters[0];
+ subtitle: Parameters[0];
+ canReset: boolean;
+} {
+ switch (view) {
+ case 'approved':
+ return {
+ title: 'oauthDeviceVerification.status.approvedTitle',
+ subtitle: 'oauthDeviceVerification.status.approvedSubtitle',
+ canReset: false,
+ };
+ case 'alreadyApproved':
+ return {
+ title: 'oauthDeviceVerification.status.alreadyApprovedTitle',
+ subtitle: 'oauthDeviceVerification.status.alreadyApprovedSubtitle',
+ canReset: false,
+ };
+ case 'denied':
+ return {
+ title: 'oauthDeviceVerification.status.deniedTitle',
+ subtitle: 'oauthDeviceVerification.status.deniedSubtitle',
+ canReset: false,
+ };
+ case 'alreadyDenied':
+ return {
+ title: 'oauthDeviceVerification.status.alreadyDeniedTitle',
+ subtitle: 'oauthDeviceVerification.status.alreadyDeniedSubtitle',
+ canReset: false,
+ };
+ case 'consumed':
+ return {
+ title: 'oauthDeviceVerification.status.consumedTitle',
+ subtitle: 'oauthDeviceVerification.status.consumedSubtitle',
+ canReset: false,
+ };
+ case 'expired':
+ return {
+ title: 'oauthDeviceVerification.error.expiredTitle',
+ subtitle: 'oauthDeviceVerification.error.expiredSubtitle',
+ canReset: false,
+ };
+ case 'rateLimited':
+ return {
+ title: 'oauthDeviceVerification.error.rateLimitedTitle',
+ subtitle: 'oauthDeviceVerification.error.rateLimitedSubtitle',
+ canReset: false,
+ };
+ case 'alreadyDecided':
+ return {
+ title: 'oauthDeviceVerification.status.alreadyDecidedTitle',
+ subtitle: 'oauthDeviceVerification.status.alreadyDecidedSubtitle',
+ canReset: false,
+ };
+ case 'error':
+ return {
+ title: 'oauthDeviceVerification.error.genericTitle',
+ subtitle: 'oauthDeviceVerification.error.genericSubtitle',
+ canReset: true,
+ };
+ }
+}
+
+const AuthenticatedRoutes = withCoreUserGuard(withCardStateProvider(OAuthDeviceVerificationInternal));
+
+export const OAuthDeviceVerification = () => (
+
+
+
+
+
+
+
+
+
+);
diff --git a/packages/ui/src/components/OAuthDeviceVerification/OAuthDeviceVerificationCodeInput.tsx b/packages/ui/src/components/OAuthDeviceVerification/OAuthDeviceVerificationCodeInput.tsx
new file mode 100644
index 00000000000..f19854aa81a
--- /dev/null
+++ b/packages/ui/src/components/OAuthDeviceVerification/OAuthDeviceVerificationCodeInput.tsx
@@ -0,0 +1,98 @@
+import type { SlotProps } from 'input-otp';
+import { OTPInput } from 'input-otp';
+
+import { Box, descriptors, Flex, Text, useAppearance } from '@/ui/customizables';
+import { OTPInputSlot } from '@/ui/elements/CodeControl';
+import { useFormField } from '@/ui/primitives/hooks/useFormField';
+import type { FormControlState } from '@/ui/utils/useFormControl';
+
+import { normalizeOAuthDeviceUserCode } from './utils';
+
+const USER_CODE_LENGTH = 8;
+const USER_CODE_GROUP_LENGTH = 4;
+
+type OAuthDeviceVerificationCodeInputProps = {
+ control: FormControlState<'userCode'>;
+};
+
+function CodeGroup({ slots, hasError }: { slots: SlotProps[]; hasError: boolean }) {
+ return (
+
+ {slots.map((slot, index) => (
+
+ ))}
+
+ );
+}
+
+export function OAuthDeviceVerificationCodeInput({ control }: OAuthDeviceVerificationCodeInputProps) {
+ const { autoFocus } = useAppearance().parsedOptions;
+ const formField = useFormField();
+ const hasError = formField.hasError ?? false;
+
+ return (
+
+ {
+ control.clearFeedback();
+ control.setValue(normalizeOAuthDeviceUserCode(value));
+ }}
+ render={({ slots }) => (
+
+
+
+ -
+
+
+
+ )}
+ />
+
+ );
+}
diff --git a/packages/ui/src/components/OAuthDeviceVerification/__tests__/OAuthDeviceVerification.test.tsx b/packages/ui/src/components/OAuthDeviceVerification/__tests__/OAuthDeviceVerification.test.tsx
new file mode 100644
index 00000000000..cfb48e064df
--- /dev/null
+++ b/packages/ui/src/components/OAuthDeviceVerification/__tests__/OAuthDeviceVerification.test.tsx
@@ -0,0 +1,457 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import type { OAuthDeviceVerificationInfo } from '@clerk/shared/types';
+import { act, within } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { bindCreateFixtures } from '@/test/create-fixtures';
+import { render, waitFor } from '@/test/utils';
+
+import { OAuthDeviceVerification } from '../OAuthDeviceVerification';
+
+const { createFixtures } = bindCreateFixtures('OAuthDeviceVerification');
+
+const verificationInfo: OAuthDeviceVerificationInfo = {
+ oauthApplicationName: 'TV App',
+ oauthApplicationLogoUrl: 'https://example.com/tv.png',
+ clientId: 'client_device',
+ scopes: [
+ { scope: 'openid', description: 'View your identity', requiresConsent: true },
+ { scope: 'email', description: 'Access your email address', requiresConsent: true },
+ ],
+ status: 'pending',
+ expiresAt: 1_800_000_000_000,
+};
+
+function apiError(code: string, status = 400) {
+ return new ClerkAPIResponseError(code, {
+ data: [{ code, message: code }],
+ status,
+ });
+}
+
+function mockOAuthApplication(
+ clerkInstance: any,
+ overrides: {
+ lookupDeviceVerification?: ReturnType;
+ submitDeviceVerification?: ReturnType;
+ } = {},
+) {
+ const oauthApplication = {
+ lookupDeviceVerification: vi.fn().mockResolvedValue(verificationInfo),
+ submitDeviceVerification: vi.fn().mockResolvedValue({
+ object: 'oauth_device_verification',
+ status: 'approved',
+ }),
+ ...overrides,
+ };
+ Object.defineProperty(clerkInstance, 'oauthApplication', {
+ configurable: true,
+ get: () => oauthApplication,
+ });
+ return oauthApplication;
+}
+
+describe('OAuthDeviceVerification', () => {
+ const originalLocation = window.location;
+
+ beforeEach(() => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ writable: true,
+ value: { ...originalLocation, search: '', href: 'https://accounts.example/device' },
+ });
+ });
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ writable: true,
+ value: originalLocation,
+ });
+ vi.clearAllMocks();
+ });
+
+ async function setup(info: OAuthDeviceVerificationInfo = verificationInfo) {
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({ email_addresses: ['jane@example.com'] });
+ });
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ const oauthApplication = mockOAuthApplication(fixtures.clerk, {
+ lookupDeviceVerification: vi.fn().mockResolvedValue(info),
+ });
+ return { wrapper, fixtures, oauthApplication };
+ }
+
+ it('uses a grouped OTP input and normalizes a forgiving entry', async () => {
+ const { wrapper, oauthApplication } = await setup();
+ const { getAllByTestId, getByLabelText, getByRole, getByTestId, getByText, userEvent } = render(
+ ,
+ { wrapper },
+ );
+
+ await userEvent.type(getByLabelText('Device code'), 'bfws zbzm');
+ expect(getByLabelText('Device code')).toHaveValue('BFWSZBZM');
+ expect(getAllByTestId('otp-input-segment')).toHaveLength(8);
+ expect(getByTestId('device-code-separator')).toHaveTextContent('-');
+ await userEvent.click(getByRole('button', { name: 'Continue' }));
+
+ await waitFor(() => expect(getByText('Allow TV App to access your account?')).toBeVisible());
+ expect(oauthApplication.lookupDeviceVerification).toHaveBeenCalledOnce();
+ expect(oauthApplication.lookupDeviceVerification).toHaveBeenCalledWith({ userCode: 'BFWSZBZM' });
+ expect(getByText('View your identity')).toBeVisible();
+ expect(getByText('Access your email address')).toBeVisible();
+ expect(getByText('Confirm this request for jane@example.com')).toBeVisible();
+ expect(getByText('Only approve this request if you started it on your other device.')).toBeVisible();
+ });
+
+ it('looks up a valid URL prefill exactly once and skips entry', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=bfws%20-zbzm' },
+ });
+ const { wrapper, oauthApplication } = await setup();
+ const { getByText, queryByRole } = render(, { wrapper });
+
+ await waitFor(() => expect(getByText('Allow TV App to access your account?')).toBeVisible());
+ expect(oauthApplication.lookupDeviceVerification).toHaveBeenCalledOnce();
+ expect(oauthApplication.lookupDeviceVerification).toHaveBeenCalledWith({ userCode: 'BFWSZBZM' });
+ expect(queryByRole('button', { name: 'Continue' })).toBeNull();
+ });
+
+ it('matches OAuthConsent scope display behavior', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper } = await setup({
+ ...verificationInfo,
+ scopes: [
+ ...verificationInfo.scopes,
+ { scope: 'offline_access', description: 'Offline access', requiresConsent: true },
+ { scope: 'private_metadata', description: 'Raw API description', requiresConsent: true },
+ ],
+ });
+ const { getByText, queryByText } = render(, { wrapper });
+
+ await waitFor(() => expect(getByText('Allow TV App to access your account?')).toBeVisible());
+ expect(queryByText('Offline access')).toBeNull();
+ expect(queryByText('offline_access')).toBeNull();
+ expect(queryByText('Raw API description')).toBeNull();
+ expect(getByText('Your private metadata set by TestApp, which may include sensitive information')).toBeVisible();
+ expect(getByText("You'll stay signed in until you sign out or revoke access.")).toBeVisible();
+ });
+
+ it('keeps an invalid URL prefill editable without calling FAPI', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=AEIO-1234' },
+ });
+ const { wrapper, oauthApplication } = await setup();
+ const { getAllByText, getByLabelText } = render(, { wrapper });
+
+ await waitFor(() => expect(getAllByText('Enter a valid 8-character code.').length).toBeGreaterThan(0));
+ expect(getByLabelText('Device code')).toHaveValue('AEIO1234');
+ expect(oauthApplication.lookupDeviceVerification).not.toHaveBeenCalled();
+ });
+
+ it('renders unknown-code errors inline and leaves the input editable', async () => {
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({ email_addresses: ['jane@example.com'] });
+ });
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ const oauthApplication = mockOAuthApplication(fixtures.clerk, {
+ lookupDeviceVerification: vi.fn().mockRejectedValue(apiError('resource_not_found', 404)),
+ });
+ const { getAllByText, getByLabelText, getByRole, userEvent } = render(, { wrapper });
+
+ await userEvent.type(getByLabelText('Device code'), 'bfwszbzm');
+ await userEvent.click(getByRole('button', { name: 'Continue' }));
+
+ await waitFor(() =>
+ expect(getAllByText("We couldn't find that code. Check it and try again.").length).toBeGreaterThan(0),
+ );
+ expect(getByLabelText('Device code')).toBeEnabled();
+ expect(oauthApplication.lookupDeviceVerification).toHaveBeenCalledOnce();
+ });
+
+ it.each([
+ ['oauth_device_code_expired', 'This code expired', 'Start over on your device.'],
+ ['too_many_requests', 'Too many attempts', 'Wait before trying another code.'],
+ ])('renders the %s lookup error distinctly without retrying', async (code, title, subtitle) => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({ email_addresses: ['jane@example.com'] });
+ });
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ const lookup = vi.fn().mockRejectedValue(apiError(code, code === 'too_many_requests' ? 429 : 400));
+ mockOAuthApplication(fixtures.clerk, { lookupDeviceVerification: lookup });
+ const { getByText } = render(, { wrapper });
+
+ await waitFor(() => expect(getByText(title)).toBeVisible());
+ expect(getByText(subtitle)).toBeVisible();
+ expect(lookup).toHaveBeenCalledOnce();
+ });
+
+ it.each([
+ ['approved', "You've approved this", 'Return to your device to continue.'],
+ ['denied', 'This request was denied', 'Start over on your device if you want to try again.'],
+ ['consumed', 'This code has already been used', 'Your device is authorized. You can close this window.'],
+ ] as const)('renders lookup status %s as an actionless past-tense report', async (status, title, subtitle) => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper } = await setup({ ...verificationInfo, status });
+ const { getByText, queryByRole, queryByText } = render(, { wrapper });
+
+ await waitFor(() => expect(getByText(title)).toBeVisible());
+ expect(getByText(subtitle)).toBeVisible();
+ expect(queryByRole('button')).toBeNull();
+ expect(queryByText('Device approved')).toBeNull();
+ });
+
+ it('falls back to a recoverable error view for an unrecognized lookup status', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper } = await setup({
+ ...verificationInfo,
+ status: 'revoked',
+ } as unknown as OAuthDeviceVerificationInfo);
+ const { getByRole, getByText } = render(, { wrapper });
+
+ await waitFor(() => expect(getByText('We could not verify this code')).toBeVisible());
+ expect(getByRole('button', { name: 'Enter another code' })).toBeVisible();
+ });
+
+ it.each([
+ ['Approve', 'approved', 'Device approved', 'You approved this request. Return to your device to continue.'],
+ ['Deny', 'denied', 'Access denied', 'You denied this request. Return to your device.'],
+ ] as const)('submits %s once and renders a fresh-decision state', async (action, status, title, subtitle) => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({ email_addresses: ['jane@example.com'] });
+ });
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ const submit = vi.fn().mockResolvedValue({ object: 'oauth_device_verification', status });
+ mockOAuthApplication(fixtures.clerk, { submitDeviceVerification: submit });
+ const { getByRole, getByText, userEvent } = render(, { wrapper });
+
+ await waitFor(() => expect(getByRole('button', { name: action })).toBeVisible());
+ await userEvent.click(getByRole('button', { name: action }));
+
+ await waitFor(() => expect(getByText(title)).toBeVisible());
+ expect(getByText(subtitle)).toBeVisible();
+ expect(submit).toHaveBeenCalledOnce();
+ expect(submit).toHaveBeenCalledWith({ userCode: 'BFWSZBZM', approved: action === 'Approve' });
+ });
+
+ it.each([
+ ['Approve', 'Deny', 'approved', 'Device approved'],
+ ['Deny', 'Approve', 'denied', 'Access denied'],
+ ] as const)('shows the decision spinner only on %s', async (action, otherAction, status, terminalTitle) => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({ email_addresses: ['jane@example.com'] });
+ });
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ let resolveSubmit: ((value: { object: string; status: string }) => void) | undefined;
+ mockOAuthApplication(fixtures.clerk, {
+ submitDeviceVerification: vi.fn().mockImplementation(
+ () =>
+ new Promise(resolve => {
+ resolveSubmit = resolve;
+ }),
+ ),
+ });
+ const { getByRole, userEvent } = render(, { wrapper });
+
+ const actionButton = await waitFor(() => getByRole('button', { name: action }));
+ const otherButton = getByRole('button', { name: otherAction });
+ await userEvent.click(actionButton);
+
+ await waitFor(() => expect(within(actionButton).getByLabelText('Loading')).toBeVisible());
+ expect(within(otherButton).queryByLabelText('Loading')).toBeNull();
+
+ await act(async () => {
+ resolveSubmit?.({ object: 'oauth_device_verification', status });
+ await Promise.resolve();
+ });
+ await waitFor(() => expect(getByRole('heading', { name: terminalTitle })).toBeVisible());
+ });
+
+ it('ignores a second decision while the first decision is pending', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({ email_addresses: ['jane@example.com'] });
+ });
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ let resolveSubmit: ((value: { object: string; status: string }) => void) | undefined;
+ const submit = vi.fn().mockImplementation(
+ () =>
+ new Promise(resolve => {
+ resolveSubmit = resolve;
+ }),
+ );
+ mockOAuthApplication(fixtures.clerk, { submitDeviceVerification: submit });
+ const { getByRole, getByText } = render(, { wrapper });
+
+ await waitFor(() => expect(getByRole('button', { name: 'Approve' })).toBeVisible());
+ act(() => {
+ getByRole('button', { name: 'Approve' }).click();
+ getByRole('button', { name: 'Deny' }).click();
+ });
+
+ expect(submit).toHaveBeenCalledOnce();
+ expect(submit).toHaveBeenCalledWith({ userCode: 'BFWSZBZM', approved: true });
+
+ await act(async () => {
+ resolveSubmit?.({ object: 'oauth_device_verification', status: 'approved' });
+ await Promise.resolve();
+ });
+ await waitFor(() => expect(getByText('Device approved')).toBeVisible());
+ });
+
+ it('renders an already-decided report without success copy for a decision-time bad_request', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({ email_addresses: ['jane@example.com'] });
+ });
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ mockOAuthApplication(fixtures.clerk, {
+ submitDeviceVerification: vi.fn().mockRejectedValue(apiError('bad_request')),
+ });
+ const { getByRole, getByText, queryByRole, queryByText, userEvent } = render(, {
+ wrapper,
+ });
+
+ await waitFor(() => expect(getByRole('button', { name: 'Approve' })).toBeVisible());
+ await userEvent.click(getByRole('button', { name: 'Approve' }));
+
+ await waitFor(() => expect(getByText('This request was already completed')).toBeVisible());
+ expect(getByText('It was decided elsewhere. Return to your device.')).toBeVisible();
+ expect(queryByText('Device approved')).toBeNull();
+ expect(queryByText('Access denied')).toBeNull();
+ expect(queryByRole('button')).toBeNull();
+ });
+
+ it('shows and defaults the organization picker only for user:org:read when organizations are enabled', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({
+ email_addresses: ['jane@example.com'],
+ organization_memberships: [
+ { id: 'org_1', name: 'Acme Corp' },
+ { id: 'org_2', name: 'Globex' },
+ ],
+ });
+ f.withOrganizations();
+ });
+ fixtures.clerk.session.lastActiveOrganizationId = 'org_2';
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ const submit = vi.fn().mockResolvedValue({ object: 'oauth_device_verification', status: 'approved' });
+ mockOAuthApplication(fixtures.clerk, {
+ lookupDeviceVerification: vi.fn().mockResolvedValue({
+ ...verificationInfo,
+ scopes: [
+ ...verificationInfo.scopes,
+ { scope: 'user:org:read', description: 'Access your organizations', requiresConsent: true },
+ ],
+ }),
+ submitDeviceVerification: submit,
+ });
+ const { getByRole, getByText, userEvent } = render(, { wrapper });
+
+ await waitFor(() => expect(getByText('Globex')).toBeVisible());
+ await userEvent.click(getByRole('button', { name: 'Approve' }));
+ expect(submit).toHaveBeenCalledWith({ userCode: 'BFWSZBZM', approved: true, organizationId: 'org_2' });
+ });
+
+ it('does not show the organization picker without user:org:read', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({
+ email_addresses: ['jane@example.com'],
+ organization_memberships: [{ id: 'org_1', name: 'Acme Corp' }],
+ });
+ f.withOrganizations();
+ });
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ mockOAuthApplication(fixtures.clerk);
+ const { getByText, queryByRole } = render(, { wrapper });
+
+ await waitFor(() => expect(getByText('Allow TV App to access your account?')).toBeVisible());
+ expect(queryByRole('combobox')).toBeNull();
+ });
+
+ it('does not show the organization picker when organizations are disabled', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper, fixtures, props } = await createFixtures(f => {
+ f.withUser({
+ email_addresses: ['jane@example.com'],
+ organization_memberships: [{ id: 'org_1', name: 'Acme Corp' }],
+ });
+ });
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ mockOAuthApplication(fixtures.clerk, {
+ lookupDeviceVerification: vi.fn().mockResolvedValue({
+ ...verificationInfo,
+ scopes: [
+ ...verificationInfo.scopes,
+ { scope: 'user:org:read', description: 'Access your organizations', requiresConsent: true },
+ ],
+ }),
+ });
+ const { getByText, queryByRole } = render(, { wrapper });
+
+ await waitFor(() => expect(getByText('Allow TV App to access your account?')).toBeVisible());
+ expect(queryByRole('combobox')).toBeNull();
+ });
+
+ it('uses the application-name fallback when no logo is provided', async () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+ const { wrapper } = await setup({ ...verificationInfo, oauthApplicationLogoUrl: null });
+ const { getByText, queryByAltText } = render(, { wrapper });
+
+ await waitFor(() => expect(getByText('Allow TV App to access your account?')).toBeVisible());
+ expect(queryByAltText('TV App')).toBeNull();
+ });
+
+ it('renders nothing and makes no request when unauthenticated', async () => {
+ const { wrapper, fixtures, props } = await createFixtures();
+ props.setProps({ componentName: 'OAuthDeviceVerification' } as any);
+ const oauthApplication = mockOAuthApplication(fixtures.clerk);
+ const { queryByText } = render(, { wrapper });
+
+ expect(queryByText('Verify a device')).toBeNull();
+ expect(oauthApplication.lookupDeviceVerification).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/ui/src/components/OAuthDeviceVerification/__tests__/utils.test.ts b/packages/ui/src/components/OAuthDeviceVerification/__tests__/utils.test.ts
new file mode 100644
index 00000000000..aa1dde3e1cc
--- /dev/null
+++ b/packages/ui/src/components/OAuthDeviceVerification/__tests__/utils.test.ts
@@ -0,0 +1,44 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { getOAuthDeviceUserCodeFromSearch, isValidOAuthDeviceUserCode, normalizeOAuthDeviceUserCode } from '../utils';
+
+describe('OAuth device user codes', () => {
+ const originalLocation = window.location;
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: originalLocation,
+ });
+ });
+
+ it.each([
+ ['bfws-zbzm', 'BFWSZBZM'],
+ [' bfws\t-\nzbzm ', 'BFWSZBZM'],
+ ['BFWSZBZM', 'BFWSZBZM'],
+ ['BFWS_ZBZM', 'BFWS_ZBZM'],
+ ])('normalizes %j to %j', (input, expected) => {
+ expect(normalizeOAuthDeviceUserCode(input)).toBe(expected);
+ });
+
+ it('removes Unicode whitespace and preserves other invalid characters', () => {
+ expect(normalizeOAuthDeviceUserCode('bfws\u00a0-\u2003zb!m')).toBe('BFWSZB!M');
+ });
+
+ it.each(['bfws-zbzm', ' BFWS ZBZM ', 'bfwsz bzm'])('accepts a valid forgiving input %j', input => {
+ expect(isValidOAuthDeviceUserCode(input)).toBe(true);
+ });
+
+ it.each(['AEIO-BCDF', 'BFWS-ZB2M', 'BFWS_ZBZM', 'BFWS-ZBZ', 'BFWS-ZBZMM'])('rejects %j', input => {
+ expect(isValidOAuthDeviceUserCode(input)).toBe(false);
+ });
+
+ it('reads user_code from the URL', () => {
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, search: '?user_code=BFWS-ZBZM' },
+ });
+
+ expect(getOAuthDeviceUserCodeFromSearch()).toBe('BFWS-ZBZM');
+ });
+});
diff --git a/packages/ui/src/components/OAuthDeviceVerification/utils.ts b/packages/ui/src/components/OAuthDeviceVerification/utils.ts
new file mode 100644
index 00000000000..03c65569071
--- /dev/null
+++ b/packages/ui/src/components/OAuthDeviceVerification/utils.ts
@@ -0,0 +1,19 @@
+const USER_CODE_PATTERN = /^[BCDFGHJKLMNPQRSTVWXZ]{8}$/;
+const USER_CODE_SEPARATOR_PATTERN = /[-\p{White_Space}]/gu;
+
+const canReadLocation = () => typeof window !== 'undefined' && !!window.location;
+
+export function normalizeOAuthDeviceUserCode(value: string): string {
+ return value.toUpperCase().replace(USER_CODE_SEPARATOR_PATTERN, '');
+}
+
+export function isValidOAuthDeviceUserCode(value: string): boolean {
+ return USER_CODE_PATTERN.test(normalizeOAuthDeviceUserCode(value));
+}
+
+export function getOAuthDeviceUserCodeFromSearch(): string {
+ if (!canReadLocation()) {
+ return '';
+ }
+ return new URLSearchParams(window.location.search).get('user_code') ?? '';
+}
diff --git a/packages/ui/src/contexts/ClerkUIComponentsContext.tsx b/packages/ui/src/contexts/ClerkUIComponentsContext.tsx
index 14371aeceaa..9fc063b9a40 100644
--- a/packages/ui/src/contexts/ClerkUIComponentsContext.tsx
+++ b/packages/ui/src/contexts/ClerkUIComponentsContext.tsx
@@ -2,6 +2,7 @@ import type {
APIKeysProps,
ConfigureSSOProps,
OAuthConsentProps,
+ OAuthDeviceVerificationProps,
PricingTableProps,
TaskChooseOrganizationProps,
TaskResetPasswordProps,
@@ -18,6 +19,7 @@ import {
CreateOrganizationContext,
GoogleOneTapContext,
OAuthConsentContext,
+ OAuthDeviceVerificationContext,
OrganizationListContext,
OrganizationProfileContext,
OrganizationSwitcherContext,
@@ -148,6 +150,12 @@ export function ComponentContextProvider({
);
}
+ case 'OAuthDeviceVerification':
+ return (
+
+ {children}
+
+ );
case 'TaskChooseOrganization':
return (
(null);
+
+export const useOAuthDeviceVerificationContext = (): OAuthDeviceVerificationCtx => {
+ const context = useContext(OAuthDeviceVerificationContext);
+
+ if (context === null) {
+ throw new Error(
+ 'Clerk: useOAuthDeviceVerificationContext called outside of the mounted OAuthDeviceVerification component.',
+ );
+ }
+
+ return context;
+};
diff --git a/packages/ui/src/contexts/components/index.ts b/packages/ui/src/contexts/components/index.ts
index 25b15a20fab..15887d4be13 100644
--- a/packages/ui/src/contexts/components/index.ts
+++ b/packages/ui/src/contexts/components/index.ts
@@ -4,6 +4,7 @@ export * from './ConfigureSSO';
export * from './CreateOrganization';
export * from './GoogleOneTap';
export * from './OAuthConsent';
+export * from './OAuthDeviceVerification';
export * from './OrganizationList';
export * from './OrganizationProfile';
export * from './OrganizationSwitcher';
diff --git a/packages/ui/src/elements/CodeControl.tsx b/packages/ui/src/elements/CodeControl.tsx
index f4896080a9b..7af93ad66fe 100644
--- a/packages/ui/src/elements/CodeControl.tsx
+++ b/packages/ui/src/elements/CodeControl.tsx
@@ -202,7 +202,7 @@ export const OTPCodeControl = () => {
role='group'
>
{slots.map((slot, index: number) => (
- {
);
};
-function Slot(props: SlotProps & PropsOfComponent & { isSuccessfullyFilled?: boolean }) {
+export function OTPInputSlot(
+ props: SlotProps & PropsOfComponent & { isSuccessfullyFilled?: boolean },
+) {
const { isSuccessfullyFilled, ...otpProps } = props;
const { char, hasFakeCaret, isActive, placeholderChar, ...rest } = otpProps;
return (
diff --git a/packages/ui/src/elements/contexts/index.tsx b/packages/ui/src/elements/contexts/index.tsx
index 379e43ebf3b..951d99b2aa4 100644
--- a/packages/ui/src/elements/contexts/index.tsx
+++ b/packages/ui/src/elements/contexts/index.tsx
@@ -100,6 +100,7 @@ export type FlowMetadata = {
| 'apiKeys'
| 'configureSSO'
| 'oauthConsent'
+ | 'oauthDeviceVerification'
| 'subscriptionDetails'
| 'tasks'
| 'taskChooseOrganization'
diff --git a/packages/ui/src/internal/appearance.ts b/packages/ui/src/internal/appearance.ts
index 9cacc2b8bc5..24c31e4e307 100644
--- a/packages/ui/src/internal/appearance.ts
+++ b/packages/ui/src/internal/appearance.ts
@@ -1161,6 +1161,7 @@ export type SubscriptionDetailsTheme = Theme;
export type APIKeysTheme = Theme;
export type ConfigureSSOTheme = Theme;
export type OAuthConsentTheme = Theme;
+export type OAuthDeviceVerificationTheme = Theme;
export type TaskChooseOrganizationTheme = Theme;
export type TaskResetPasswordTheme = Theme;
export type TaskSetupMFATheme = Theme;
@@ -1244,6 +1245,10 @@ export type Appearance = T &
* Theme overrides that only apply to the `` component
*/
__internal_oauthConsent?: T;
+ /**
+ * Theme overrides that only apply to the `` component
+ */
+ oauthDeviceVerification?: T;
/**
* Theme overrides that only apply to the `` component
*/
diff --git a/packages/ui/src/internal/index.ts b/packages/ui/src/internal/index.ts
index d86140b52a0..16722dbdda5 100644
--- a/packages/ui/src/internal/index.ts
+++ b/packages/ui/src/internal/index.ts
@@ -74,6 +74,7 @@ export type {
IdSelectors,
Options,
OAuthConsentTheme,
+ OAuthDeviceVerificationTheme,
OrganizationListTheme,
OrganizationProfileTheme,
OrganizationSwitcherTheme,
diff --git a/packages/ui/src/lazyModules/components.ts b/packages/ui/src/lazyModules/components.ts
index a6564663a43..9d4a9a87148 100644
--- a/packages/ui/src/lazyModules/components.ts
+++ b/packages/ui/src/lazyModules/components.ts
@@ -32,6 +32,10 @@ const componentImportPaths = {
APIKeys: () => import(/* webpackChunkName: "apiKeys" */ '../components/APIKeys/APIKeys'),
ConfigureSSO: () => import(/* webpackChunkName: "configureSSO" */ '../components/ConfigureSSO/ConfigureSSO'),
OAuthConsent: () => import(/* webpackChunkName: "oauthConsent" */ '../components/OAuthConsent/OAuthConsent'),
+ OAuthDeviceVerification: () =>
+ import(
+ /* webpackChunkName: "oauthDeviceVerification" */ '../components/OAuthDeviceVerification/OAuthDeviceVerification'
+ ),
EnableOrganizationsPrompt: () =>
import(/* webpackChunkName: "enableOrganizationsPrompt" */ '../components/devPrompts/EnableOrganizationsPrompt'),
} as const;
@@ -156,6 +160,10 @@ export const OAuthConsent = lazy(() =>
componentImportPaths.OAuthConsent().then(module => ({ default: module.OAuthConsent })),
);
+export const OAuthDeviceVerification = lazy(() =>
+ componentImportPaths.OAuthDeviceVerification().then(module => ({ default: module.OAuthDeviceVerification })),
+);
+
export const SessionTasks = lazy(() =>
componentImportPaths.SessionTasks().then(module => ({ default: module.SessionTasks })),
);
@@ -193,6 +201,7 @@ export const ClerkComponents = {
APIKeys,
ConfigureSSO,
OAuthConsent,
+ OAuthDeviceVerification,
SubscriptionDetails,
TaskChooseOrganization,
TaskResetPassword,
diff --git a/packages/ui/src/types.ts b/packages/ui/src/types.ts
index 3a674696c4b..31e10f59920 100644
--- a/packages/ui/src/types.ts
+++ b/packages/ui/src/types.ts
@@ -10,6 +10,7 @@ import type {
GoogleOneTapProps,
NewSubscriptionRedirectUrl,
OAuthConsentProps,
+ OAuthDeviceVerificationProps,
OrganizationListProps,
OrganizationProfileProps,
OrganizationSwitcherProps,
@@ -34,6 +35,7 @@ import type { WithInternalRouting } from './internal';
export type {
OAuthConsentProps,
+ OAuthDeviceVerificationProps,
__internal_UserVerificationProps,
CreateOrganizationProps,
GoogleOneTapProps,
@@ -67,6 +69,7 @@ export type AvailableComponentProps =
| APIKeysProps
| ConfigureSSOProps
| OAuthConsentProps
+ | OAuthDeviceVerificationProps
| TaskChooseOrganizationProps
| TaskResetPasswordProps
| TaskSetupMFAProps;
@@ -227,6 +230,10 @@ export type OAuthConsentCtx = {
appearance?: ClerkAppearanceTheme;
};
+export type OAuthDeviceVerificationCtx = OAuthDeviceVerificationProps & {
+ componentName: 'OAuthDeviceVerification';
+};
+
export type SubscriptionDetailsCtx = __internal_SubscriptionDetailsProps & {
componentName: 'SubscriptionDetails';
};
@@ -253,6 +260,7 @@ export type AvailableComponentCtx =
| APIKeysCtx
| ConfigureSSOCtx
| OAuthConsentCtx
+ | OAuthDeviceVerificationCtx
| SubscriptionDetailsCtx
| PlanDetailsCtx
| TaskChooseOrganizationCtx
diff --git a/packages/vue/src/components/index.ts b/packages/vue/src/components/index.ts
index 10f7d6aa756..0765b7c426e 100644
--- a/packages/vue/src/components/index.ts
+++ b/packages/vue/src/components/index.ts
@@ -7,6 +7,7 @@ export { default as OrganizationList } from './ui-components/OrganizationList.vu
export { default as PricingTable } from './ui-components/PricingTable.vue';
export { default as APIKeys } from './ui-components/APIKeys.vue';
export { default as OAuthConsent } from './ui-components/OAuthConsent.vue';
+export { default as OAuthDeviceVerification } from './ui-components/OAuthDeviceVerification.vue';
export { UserProfile } from './ui-components/UserProfile';
export { OrganizationProfile } from './ui-components/OrganizationProfile';
export { OrganizationSwitcher } from './ui-components/OrganizationSwitcher';
diff --git a/packages/vue/src/components/ui-components/OAuthDeviceVerification.vue b/packages/vue/src/components/ui-components/OAuthDeviceVerification.vue
new file mode 100644
index 00000000000..627322c4edb
--- /dev/null
+++ b/packages/vue/src/components/ui-components/OAuthDeviceVerification.vue
@@ -0,0 +1,17 @@
+
+
+
+
+