chore(backend): Rename machine auth verification methods

.changeset/spotty-wasps-smoke.md

@@ -0,0 +1,19 @@
+---
+'@clerk/backend': minor
+---
+
+Unified machine token verification methods under a consistent `verify()` API. The previous methods (`verifySecret`, `verifyToken`, `verifyAccessToken`) are now deprecated.
+
+Before
+
+```ts
+await clerkClient.apiKeys.verifySecret('ak_...');
+await clerkClient.m2m.verifyToken({ token: 'mt_...' });
+```
+
+After
+
+```ts
+await clerkClient.apiKeys.verify('ak_...');
+await clerkClient.m2m.verify({ token: 'mt_...' });
+```

packages/backend/src/api/__tests__/M2MTokenApi.test.ts

@@ -206,7 +206,7 @@ describe('M2MToken', () => {
     });
   });
 
-  describe('verifyToken', () => {
+  describe('verify', () => {
     it('verifies a m2m token using machine secret', async () => {
       const apiClient = createBackendApiClient({
         apiUrl: 'https://api.clerk.test',
@@ -223,7 +223,7 @@ describe('M2MToken', () => {
         ),
       );
 
-      const response = await apiClient.m2m.verifyToken({
+      const response = await apiClient.m2m.verify({
         token: m2mSecret,
       });
 
@@ -249,7 +249,7 @@ describe('M2MToken', () => {
         ),
       );
 
-      const response = await apiClient.m2m.verifyToken({
+      const response = await apiClient.m2m.verify({
         token: m2mSecret,
       });
 
@@ -274,7 +274,7 @@ describe('M2MToken', () => {
       );
 
       const errResponse = await apiClient.m2m
-        .verifyToken({
+        .verify({
           token: m2mSecret,
         })
         .catch(err => err);

packages/backend/src/api/__tests__/factory.test.ts

@@ -325,7 +325,7 @@ describe('api.client', () => {
         ),
       );
 
-      const response = await apiClient.m2m.verifyToken({
+      const response = await apiClient.m2m.verify({
         machineSecretKey: 'ak_test_in_header_params', // this will be added to headerParams.Authorization
         token: 'mt_secret_test',
       });
@@ -353,7 +353,7 @@ describe('api.client', () => {
         ),
       );
 
-      const response = await apiClient.m2m.verifyToken({
+      const response = await apiClient.m2m.verify({
         token: 'mt_secret_test',
       });
       expect(response.id).toBe('mt_test');
@@ -425,7 +425,7 @@ describe('api.client', () => {
         ),
       );
 
-      const response = await apiClient.m2m.verifyToken({
+      const response = await apiClient.m2m.verify({
         token: 'mt_secret_test',
       });
       expect(response.id).toBe('mt_test');

packages/backend/src/api/endpoints/APIKeysApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest } from '@clerk/shared/types';
 
 import type { PaginatedResourceResponse } from '../../api/resources/Deserializer';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type { APIKey } from '../resources/APIKey';
 import { AbstractAPI } from './AbstractApi';
 
@@ -88,11 +89,19 @@ export class APIKeysAPI extends AbstractAPI {
     });
   }
 
-  async verifySecret(secret: string) {
+  async verify(secret: string) {
     return this.request<APIKey>({
       method: 'POST',
       path: joinPaths(basePath, 'verify'),
       bodyParams: { secret },
     });
   }
+
+  /**
+   * @deprecated Use `verify()` instead. This method will be removed in the next major release.
+   */
+  async verifySecret(secret: string) {
+    deprecated('apiKeys.verifySecret()', 'Use `apiKeys.verify()` instead.');
+    return this.verify(secret);
+  }
 }

packages/backend/src/api/endpoints/IdPOAuthAccessTokenApi.ts

@@ -1,15 +1,24 @@
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type { IdPOAuthAccessToken } from '../resources';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/oauth_applications/access_tokens';
 
 export class IdPOAuthAccessTokenApi extends AbstractAPI {
-  async verifyAccessToken(accessToken: string) {
+  async verify(accessToken: string) {
     return this.request<IdPOAuthAccessToken>({
       method: 'POST',
       path: joinPaths(basePath, 'verify'),
       bodyParams: { access_token: accessToken },
     });
   }
+
+  /**
+   * @deprecated Use `verify()` instead. This method will be removed in the next major release.
+   */
+  async verifyAccessToken(accessToken: string) {
+    deprecated('idPOAuthAccessToken.verifyAccessToken()', 'Use `idPOAuthAccessToken.verify()` instead.');
+    return this.verify(accessToken);
+  }
 }

packages/backend/src/api/endpoints/M2MTokenApi.ts

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type { ClerkBackendApiRequestOptions } from '../request';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
@@ -94,7 +95,7 @@ export class M2MTokenApi extends AbstractAPI {
     return this.request<M2MToken>(requestOptions);
   }
 
-  async verifyToken(params: VerifyM2MTokenParams) {
+  async verify(params: VerifyM2MTokenParams) {
     const { token, machineSecretKey } = params;
 
     const requestOptions = this.#createRequestOptions(
@@ -108,4 +109,12 @@ export class M2MTokenApi extends AbstractAPI {
 
     return this.request<M2MToken>(requestOptions);
   }
+
+  /**
+   * @deprecated Use `verify()` instead. This method will be removed in the next major release.
+   */
+  async verifyToken(params: VerifyM2MTokenParams) {
+    deprecated('m2m.verifyToken()', 'Use `m2m.verify()` instead.');
+    return this.verify(params);
+  }
 }

packages/backend/src/tokens/verify.ts

@@ -199,7 +199,7 @@ async function verifyM2MToken(
 ): Promise<MachineTokenReturnType<M2MToken, MachineTokenVerificationError>> {
   try {
     const client = createBackendApiClient(options);
-    const verifiedToken = await client.m2m.verifyToken({ token });
+    const verifiedToken = await client.m2m.verify({ token });
     return { data: verifiedToken, tokenType: TokenType.M2MToken, errors: undefined };
   } catch (err: any) {
     return handleClerkAPIError(TokenType.M2MToken, err, 'Machine token not found');
@@ -212,7 +212,7 @@ async function verifyOAuthToken(
 ): Promise<MachineTokenReturnType<IdPOAuthAccessToken, MachineTokenVerificationError>> {
   try {
     const client = createBackendApiClient(options);
-    const verifiedToken = await client.idPOAuthAccessToken.verifyAccessToken(accessToken);
+    const verifiedToken = await client.idPOAuthAccessToken.verify(accessToken);
     return { data: verifiedToken, tokenType: TokenType.OAuthToken, errors: undefined };
   } catch (err: any) {
     return handleClerkAPIError(TokenType.OAuthToken, err, 'OAuth token not found');
@@ -225,7 +225,7 @@ async function verifyAPIKey(
 ): Promise<MachineTokenReturnType<APIKey, MachineTokenVerificationError>> {
   try {
     const client = createBackendApiClient(options);
-    const verifiedToken = await client.apiKeys.verifySecret(secret);
+    const verifiedToken = await client.apiKeys.verify(secret);
     return { data: verifiedToken, tokenType: TokenType.ApiKey, errors: undefined };
   } catch (err: any) {
     return handleClerkAPIError(TokenType.ApiKey, err, 'API key not found');