From 02858053a32711d1418db5f83aee4b04350c6892 Mon Sep 17 00:00:00 2001
From: Sarah Soutoul <sarah@clerk.dev>
Date: Mon, 7 Sep 2026 14:07:00 -0600
Subject: [PATCH] docs(shared): document OAuth device verification types

---
 .changeset/oauth-device-verification-docs.md  |  5 ++
 .../hooks/useOAuthDeviceVerification.types.ts | 32 +++++++++++
 packages/shared/src/types/oauthApplication.ts | 56 ++++++++++++++++++-
 3 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/oauth-device-verification-docs.md

diff --git a/.changeset/oauth-device-verification-docs.md b/.changeset/oauth-device-verification-docs.md
new file mode 100644
index 00000000000..37316627ebf
--- /dev/null
+++ b/.changeset/oauth-device-verification-docs.md
@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Document the public fields, actions, and parameter types for OAuth device verification flows.
diff --git a/packages/shared/src/react/hooks/useOAuthDeviceVerification.types.ts b/packages/shared/src/react/hooks/useOAuthDeviceVerification.types.ts
index 9b223a58caf..0dd1a8279a9 100644
--- a/packages/shared/src/react/hooks/useOAuthDeviceVerification.types.ts
+++ b/packages/shared/src/react/hooks/useOAuthDeviceVerification.types.ts
@@ -9,14 +9,46 @@ import type {
 
 type DecisionParams = Omit<SubmitOAuthDeviceVerificationParams, 'approved'>;
 
+/**
+ * The current state and actions for an OAuth device verification flow.
+ *
+ * @interface
+ */
 export type UseOAuthDeviceVerificationReturn = {
+  /**
+   * Information about the device authorization returned by the latest successful lookup, or `undefined` if no lookup has succeeded.
+   */
   data: OAuthDeviceVerificationInfo | undefined;
+  /**
+   * The result of the latest approval or denial, or `undefined` if no decision has succeeded.
+   */
   result: OAuthDeviceVerificationResult | undefined;
+  /**
+   * The most recent error returned while looking up or submitting a device authorization, or `null` if no error occurred.
+   */
   error: ClerkAPIResponseError | ClerkRuntimeError | null;
+  /**
+   * Whether a device authorization lookup is in progress.
+   */
   isLoading: boolean;
+  /**
+   * Whether an approval or denial is in progress.
+   */
   isSubmitting: boolean;
+  /**
+   * Looks up a device authorization by its user code.
+   */
   lookup: (params: LookupOAuthDeviceVerificationParams) => Promise<OAuthDeviceVerificationInfo>;
+  /**
+   * Approves a device authorization.
+   */
   approve: (params: DecisionParams) => Promise<OAuthDeviceVerificationResult>;
+  /**
+   * Denies a device authorization.
+   */
   deny: (params: LookupOAuthDeviceVerificationParams) => Promise<OAuthDeviceVerificationResult>;
+  /**
+   * Clears the current device authorization state.
+   */
   reset: () => void;
 };
diff --git a/packages/shared/src/types/oauthApplication.ts b/packages/shared/src/types/oauthApplication.ts
index 584c976bc65..4ca73719910 100644
--- a/packages/shared/src/types/oauthApplication.ts
+++ b/packages/shared/src/types/oauthApplication.ts
@@ -101,31 +101,63 @@ export type OAuthConsentInfo = {
   scopes: OAuthConsentScope[];
 };
 
+/**
+ * The current status of an OAuth device authorization.
+ */
 export type OAuthDeviceVerificationStatus = 'pending' | 'approved' | 'denied' | 'consumed';
 
 /**
  * A scope requested by an OAuth device authorization.
+ *
+ * @interface
  */
 export type OAuthDeviceVerificationScope = OAuthConsentScope;
 
 /**
  * Information about an OAuth device authorization awaiting verification.
+ *
+ * @interface
  */
 export type OAuthDeviceVerificationInfo = {
+  /**
+   * The display name of the OAuth application requesting authorization.
+   */
   oauthApplicationName: string;
+  /**
+   * The URL of the OAuth application's logo image, or `null` if no logo is available.
+   */
   oauthApplicationLogoUrl: string | null;
+  /**
+   * The OAuth `client_id` that identifies the application requesting authorization.
+   */
   clientId: string;
+  /**
+   * The scopes the OAuth application is requesting.
+   */
   scopes: OAuthDeviceVerificationScope[];
+  /**
+   * The current status of the device authorization.
+   */
   status: OAuthDeviceVerificationStatus;
-  /** Expiration time as Unix milliseconds. */
+  /**
+   * The expiration time of the device authorization, as a Unix timestamp in milliseconds.
+   */
   expiresAt: number;
 };
 
 /**
  * The result of approving or denying an OAuth device authorization.
+ *
+ * @interface
  */
 export type OAuthDeviceVerificationResult = {
+  /**
+   * The type of the resource.
+   */
   object: 'oauth_device_verification';
+  /**
+   * The final decision for the device authorization.
+   */
   status: Extract<OAuthDeviceVerificationStatus, 'approved' | 'denied'>;
 };
 
@@ -138,13 +170,35 @@ export type GetOAuthConsentInfoParams = {
   redirectUri?: string;
 };
 
+/**
+ * The parameters for looking up an OAuth device authorization.
+ *
+ * @interface
+ */
 export type LookupOAuthDeviceVerificationParams = {
+  /**
+   * The user code displayed by the device requesting authorization.
+   */
   userCode: string;
 };
 
+/**
+ * The parameters for approving or denying an OAuth device authorization.
+ *
+ * @interface
+ */
 export type SubmitOAuthDeviceVerificationParams = {
+  /**
+   * The user code displayed by the device requesting authorization.
+   */
   userCode: string;
+  /**
+   * Whether to approve or deny the authorization request.
+   */
   approved: boolean;
+  /**
+   * The ID of the Organization to authorize the request for. Omit this to authorize the request for the user's personal account.
+   */
   organizationId?: string;
 };