chore(backend): Improve subject handling for machine auth objects

.changeset/mean-items-retire.md

@@ -0,0 +1,36 @@
+---
+"@clerk/backend": minor
+---
+
+Improve `subject` property handling for machine auth objects.
+
+Usage:
+
+```ts
+import { createClerkClient } from '@clerk/backend'
+
+const clerkClient = createClerkClient({
+ secretKey: process.env.CLERK_SECRET_KEY,
+ publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+})
+
+const requestState = await clerkClient.authenticateRequest(request, {
+ acceptsToken: 'any',
+})
+
+const authObject = requestState.toAuth()
+
+switch (authObject.tokenType) {
+ case 'api_key':
+ // authObject.userId
+ // authObject.orgId
+ break;
+ case 'machine_token':
+ // authObject.machineId
+ break;
+ case 'oauth_token':
+ // authObject.userId
+ // authObject.clientId
+ break;
+}
+```

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

@@ -5,11 +5,11 @@ import { AbstractAPI } from './AbstractApi';
 const basePath = '/oauth_applications/access_tokens';
 
 export class IdPOAuthAccessTokenApi extends AbstractAPI {
- async verifySecret(secret: string) {
+ async verifyAccessToken(accessToken: string) {
  return this.request<IdPOAuthAccessToken>({
  method: 'POST',
  path: joinPaths(basePath, 'verify'),
- bodyParams: { secret },
+ bodyParams: { access_token: accessToken },
  });
  }
 }

packages/backend/src/fixtures/machine.ts

@@ -37,9 +37,9 @@ export const mockVerificationResults = {
  updatedAt: 1744928754551,
  },
  machine_token: {
- id: 'mt_ey966f1b1xf93586b2debdcadb0b3bd1',
+ id: 'm2m_ey966f1b1xf93586b2debdcadb0b3bd1',
  name: 'my-machine-token',
- subject: 'user_2vYVtestTESTtestTESTtestTESTtest',
+ subject: 'mch_2vYVtestTESTtestTESTtestTESTtest',
  scopes: ['read:foo', 'write:bar'],
  claims: { foo: 'bar' },
  revoked: false,

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -280,13 +280,34 @@ describe('authenticatedMachineObject', () => {
  expect(authObject.has({})).toBe(false);
  });
 
- it('properly initializes properties', () => {
+ it('properly initializes properties (user)', () => {
  const authObject = authenticatedMachineObject('api_key', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('api_key');
- expect(authObject.name).toBe('my-api-key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.orgId).toBeNull();
+ });
+
+ it('properly initializes properties (org)', () => {
+ const authObject = authenticatedMachineObject(
+ 'api_key',
+ token,
+ {
+ ...verificationResult,
+ subject: 'org_2vYVtestTESTtestTESTtestTESTtest',
+ },
+ debugData,
+ );
+ expect(authObject.tokenType).toBe('api_key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBeNull();
+ expect(authObject.orgId).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 
@@ -308,8 +329,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('oauth_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('oauth_token');
+ expect(authObject.id).toBe('oat_2VTWUzvGC5UhdJCNx6xG1D98edc');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.clientId).toBe('client_2VTWUzvGC5UhdJCNx6xG1D98edc');
  });
  });
 
@@ -332,10 +356,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('machine_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('machine_token');
- expect(authObject.name).toBe('my-machine-token');
- expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.machineId).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 });

packages/backend/src/tokens/__tests__/getAuth.test-d.ts

@@ -1,4 +1,4 @@
-import { assertType, expectTypeOf, test } from 'vitest';
+import { expectTypeOf, test } from 'vitest';
 
 import type { AuthObject } from '../authObjects';
 import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
@@ -32,76 +32,18 @@ test('infers the correct AuthObject type for each accepted token type', () => {
  expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
 });
 
-test('verifies correct properties exist for each token type', () => {
- const request = new Request('https://example.com');
-
- // Session token should have userId
- const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
- expectTypeOf(sessionAuth.userId).toMatchTypeOf<string | null>();
-
- // All machine tokens should have id and subject
- const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
- const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
- const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
-
- expectTypeOf(apiKeyAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.subject).toMatchTypeOf<string | null>();
-
- // Only api_key and machine_token should have name and claims
- expectTypeOf(apiKeyAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- expectTypeOf(machineTokenAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- // oauth_token should NOT have name and claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(oauthTokenAuth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(oauthTokenAuth.claims);
-});
-
 test('verifies discriminated union works correctly with acceptsToken: any', () => {
  const request = new Request('https://example.com');
 
  const auth = getAuth(request, { acceptsToken: 'any' });
 
  if (auth.tokenType === 'session_token') {
- // Should be SessionAuthObject - has userId
- expectTypeOf(auth.userId).toMatchTypeOf<string | null>();
- // Should NOT have machine token properties
- // @ts-expect-error session_token does not have id property
- assertType<string | null>(auth.id);
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
  } else if (auth.tokenType === 'api_key') {
- // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error api_key does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
  } else if (auth.tokenType === 'machine_token') {
- // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error machine_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
  } else if (auth.tokenType === 'oauth_token') {
- // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- // Should NOT have name or claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(auth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(auth.claims);
- // Should NOT have session token properties
- // @ts-expect-error oauth_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
  }
 });

packages/backend/src/tokens/__tests__/verify.test.ts

@@ -119,9 +119,9 @@ describe('tokens.verifyMachineAuthToken(token, options)', () => {
  expect(result.errors).toBeUndefined();
 
  const data = result.data as MachineToken;
- expect(data.id).toBe('mt_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(data.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(data.name).toBe('my-machine-token');
- expect(data.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(data.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(data.scopes).toEqual(['read:foo', 'write:bar']);
  expect(data.claims).toEqual({ foo: 'bar' });
  });

packages/backend/src/tokens/authObjects.ts

@@ -11,7 +11,7 @@ import type {
  SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
-import type { APIKey, CreateBackendApiOptions, MachineToken } from '../api';
+import type { APIKey, CreateBackendApiOptions, IdPOAuthAccessToken, MachineToken } from '../api';
 import { createBackendApiClient } from '../api';
 import { isTokenTypeAccepted } from '../internal';
 import type { AuthenticateContext } from './authenticateContext';
@@ -84,22 +84,23 @@ export type SignedOutAuthObject = {
  * While all machine token types share common properties (id, name, subject, etc),
  * this type defines the additional properties that are unique to each token type.
  *
- * @example
- * api_key & machine_token: adds `claims` property
- * oauth_token: adds no additional properties (empty object)
- *
  * @template TAuthenticated - Whether the machine object is authenticated or not
  */
 type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
- api_key: {
- name: TAuthenticated extends true ? string : null;
- claims: TAuthenticated extends true ? Claims | null : null;
- };
+ api_key: TAuthenticated extends true
+ ?
+ | { name: string; claims: Claims | null; userId: string; orgId: null }
+ | { name: string; claims: Claims | null; userId: null; orgId: string }
+ : { name: null; claims: null; userId: null; orgId: null };
  machine_token: {
  name: TAuthenticated extends true ? string : null;
  claims: TAuthenticated extends true ? Claims | null : null;
+ machineId: TAuthenticated extends true ? string : null;
+ };
+ oauth_token: {
+ userId: TAuthenticated extends true ? string : null;
+ clientId: TAuthenticated extends true ? string : null;
  };
- oauth_token: object;
 };
 
 /**
@@ -257,6 +258,8 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ userId: result.subject.startsWith('user_') ? result.subject : null,
+ orgId: result.subject.startsWith('org_') ? result.subject : null,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -267,14 +270,18 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ machineId: result.subject,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
+ const result = verificationResult as IdPOAuthAccessToken;
  return {
  ...baseObject,
  tokenType,
- scopes: verificationResult.scopes,
- } as AuthenticatedMachineObject<T>;
+ scopes: result.scopes,
+ userId: result.subject,
+ clientId: result.clientId,
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -304,6 +311,9 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ userId: null,
+ orgId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -312,13 +322,18 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ machineId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
  ...baseObject,
  tokenType,
- } as UnauthenticatedMachineObject<T>;
+ scopes: null,
+ userId: null,
+ clientId: null,
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -406,7 +421,7 @@ export const getAuthObjectFromJwt = (
  *
  * @example
  * // Accept 'api_key' or 'machine_token'
- * const authObject = { tokenType: 'machine_token', id: 'mt_123' };
+ * const authObject = { tokenType: 'machine_token', id: 'm2m_123' };
  * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: ['api_key', 'machine_token'] });
  * // result will be the original authObject (since tokenType matches one in the array)
  *

packages/backend/src/tokens/verify.ts

@@ -214,12 +214,12 @@ async function verifyMachineToken(
 }
 
 async function verifyOAuthToken(
-secret: string,
+accessToken: string,
  options: VerifyTokenOptions,
 ): Promise<MachineTokenReturnType<IdPOAuthAccessToken, MachineTokenVerificationError>> {
  try {
  const client = createBackendApiClient(options);
- const verifiedToken = await client.idPOAuthAccessToken.verifySecret(secret);
+ const verifiedToken = await client.idPOAuthAccessToken.verifyAccessToken(accessToken);
  return { data: verifiedToken, tokenType: TokenType.OAuthToken, errors: undefined };
  } catch (err: any) {
  return handleClerkAPIError(TokenType.OAuthToken, err, 'OAuth token not found');

packages/express/src/__tests__/getAuth.test.ts

@@ -21,18 +21,19 @@ describe('getAuth', () => {
  });
 
  it('returns the actual auth object when its tokenType matches acceptsToken', () => {
- const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', subject: 'api_key_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', userId: 'user_12345', orgId: null });
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('api_key');
  expect(result.id).toBe('ak_1234');
- expect(result.subject).toBe('api_key_1234');
+ expect(result.userId).toBe('user_12345');
+ expect(result.orgId).toBeNull();
  });
 
  it('returns the actual auth object if its tokenType is included in the acceptsToken array', () => {
- const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'mt_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'm2m_1234' });
  const result = getAuth(req, { acceptsToken: ['machine_token', 'api_key'] });
  expect(result.tokenType).toBe('machine_token');
- expect(result.id).toBe('mt_1234');
+ expect(result.id).toBe('m2m_1234');
  expect(result.subject).toBeUndefined();
  });
 
@@ -41,7 +42,7 @@ describe('getAuth', () => {
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('session_token'); // reflects the actual token found
  // Properties specific to authenticated objects should be null or undefined
- // @ts-expect-error - userId is not a property of the unauthenticated object
  expect(result.userId).toBeNull();
+ expect(result.orgId).toBeNull();
  });
 });

.changeset/mean-items-retire.md

@@ -0,0 +1,36 @@
+---
+"@clerk/backend": minor
+---
+
+Improve `subject` property handling for machine auth objects.
+
+Usage:
+
+```ts
+import { createClerkClient } from '@clerk/backend'
+
+const clerkClient = createClerkClient({
+ secretKey: process.env.CLERK_SECRET_KEY,
+ publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+})
+
+const requestState = await clerkClient.authenticateRequest(request, {
+ acceptsToken: 'any',
+})
+
+const authObject = requestState.toAuth()
+
+switch (authObject.tokenType) {
+ case 'api_key':
+ // authObject.userId
+ // authObject.orgId
+ break;
+ case 'machine_token':
+ // authObject.machineId
+ break;
+ case 'oauth_token':
+ // authObject.userId
+ // authObject.clientId
+ break;
+}
+```

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

@@ -5,11 +5,11 @@ import { AbstractAPI } from './AbstractApi';
 const basePath = '/oauth_applications/access_tokens';
 
 export class IdPOAuthAccessTokenApi extends AbstractAPI {
- async verifySecret(secret: string) {
+ async verifyAccessToken(accessToken: string) {
  return this.request<IdPOAuthAccessToken>({
  method: 'POST',
  path: joinPaths(basePath, 'verify'),
- bodyParams: { secret },
+ bodyParams: { access_token: accessToken },
  });
  }
 }

packages/backend/src/fixtures/machine.ts

@@ -37,9 +37,9 @@ export const mockVerificationResults = {
  updatedAt: 1744928754551,
  },
  machine_token: {
- id: 'mt_ey966f1b1xf93586b2debdcadb0b3bd1',
+ id: 'm2m_ey966f1b1xf93586b2debdcadb0b3bd1',
  name: 'my-machine-token',
- subject: 'user_2vYVtestTESTtestTESTtestTESTtest',
+ subject: 'mch_2vYVtestTESTtestTESTtestTESTtest',
  scopes: ['read:foo', 'write:bar'],
  claims: { foo: 'bar' },
  revoked: false,

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -280,13 +280,34 @@ describe('authenticatedMachineObject', () => {
  expect(authObject.has({})).toBe(false);
  });
 
- it('properly initializes properties', () => {
+ it('properly initializes properties (user)', () => {
  const authObject = authenticatedMachineObject('api_key', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('api_key');
- expect(authObject.name).toBe('my-api-key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.orgId).toBeNull();
+ });
+
+ it('properly initializes properties (org)', () => {
+ const authObject = authenticatedMachineObject(
+ 'api_key',
+ token,
+ {
+ ...verificationResult,
+ subject: 'org_2vYVtestTESTtestTESTtestTESTtest',
+ },
+ debugData,
+ );
+ expect(authObject.tokenType).toBe('api_key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBeNull();
+ expect(authObject.orgId).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 
@@ -308,8 +329,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('oauth_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('oauth_token');
+ expect(authObject.id).toBe('oat_2VTWUzvGC5UhdJCNx6xG1D98edc');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.clientId).toBe('client_2VTWUzvGC5UhdJCNx6xG1D98edc');
  });
  });
 
@@ -332,10 +356,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('machine_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('machine_token');
- expect(authObject.name).toBe('my-machine-token');
- expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.machineId).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 });

packages/backend/src/tokens/__tests__/getAuth.test-d.ts

@@ -1,4 +1,4 @@
-import { assertType, expectTypeOf, test } from 'vitest';
+import { expectTypeOf, test } from 'vitest';
 
 import type { AuthObject } from '../authObjects';
 import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
@@ -32,76 +32,18 @@ test('infers the correct AuthObject type for each accepted token type', () => {
  expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
 });
 
-test('verifies correct properties exist for each token type', () => {
- const request = new Request('https://example.com');
-
- // Session token should have userId
- const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
- expectTypeOf(sessionAuth.userId).toMatchTypeOf<string | null>();
-
- // All machine tokens should have id and subject
- const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
- const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
- const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
-
- expectTypeOf(apiKeyAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.subject).toMatchTypeOf<string | null>();
-
- // Only api_key and machine_token should have name and claims
- expectTypeOf(apiKeyAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- expectTypeOf(machineTokenAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- // oauth_token should NOT have name and claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(oauthTokenAuth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(oauthTokenAuth.claims);
-});
-
 test('verifies discriminated union works correctly with acceptsToken: any', () => {
  const request = new Request('https://example.com');
 
  const auth = getAuth(request, { acceptsToken: 'any' });
 
  if (auth.tokenType === 'session_token') {
- // Should be SessionAuthObject - has userId
- expectTypeOf(auth.userId).toMatchTypeOf<string | null>();
- // Should NOT have machine token properties
- // @ts-expect-error session_token does not have id property
- assertType<string | null>(auth.id);
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
  } else if (auth.tokenType === 'api_key') {
- // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error api_key does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
  } else if (auth.tokenType === 'machine_token') {
- // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error machine_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
  } else if (auth.tokenType === 'oauth_token') {
- // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- // Should NOT have name or claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(auth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(auth.claims);
- // Should NOT have session token properties
- // @ts-expect-error oauth_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
  }
 });

packages/backend/src/tokens/__tests__/verify.test.ts

@@ -119,9 +119,9 @@ describe('tokens.verifyMachineAuthToken(token, options)', () => {
  expect(result.errors).toBeUndefined();
 
  const data = result.data as MachineToken;
- expect(data.id).toBe('mt_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(data.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(data.name).toBe('my-machine-token');
- expect(data.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(data.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(data.scopes).toEqual(['read:foo', 'write:bar']);
  expect(data.claims).toEqual({ foo: 'bar' });
  });

packages/backend/src/tokens/authObjects.ts

@@ -11,7 +11,7 @@ import type {
  SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
-import type { APIKey, CreateBackendApiOptions, MachineToken } from '../api';
+import type { APIKey, CreateBackendApiOptions, IdPOAuthAccessToken, MachineToken } from '../api';
 import { createBackendApiClient } from '../api';
 import { isTokenTypeAccepted } from '../internal';
 import type { AuthenticateContext } from './authenticateContext';
@@ -84,22 +84,23 @@ export type SignedOutAuthObject = {
  * While all machine token types share common properties (id, name, subject, etc),
  * this type defines the additional properties that are unique to each token type.
  *
- * @example
- * api_key & machine_token: adds `claims` property
- * oauth_token: adds no additional properties (empty object)
- *
  * @template TAuthenticated - Whether the machine object is authenticated or not
  */
 type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
- api_key: {
- name: TAuthenticated extends true ? string : null;
- claims: TAuthenticated extends true ? Claims | null : null;
- };
+ api_key: TAuthenticated extends true
+ ?
+ | { name: string; claims: Claims | null; userId: string; orgId: null }
+ | { name: string; claims: Claims | null; userId: null; orgId: string }
+ : { name: null; claims: null; userId: null; orgId: null };
  machine_token: {
  name: TAuthenticated extends true ? string : null;
  claims: TAuthenticated extends true ? Claims | null : null;
+ machineId: TAuthenticated extends true ? string : null;
+ };
+ oauth_token: {
+ userId: TAuthenticated extends true ? string : null;
+ clientId: TAuthenticated extends true ? string : null;
  };
- oauth_token: object;
 };
 
 /**
@@ -257,6 +258,8 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ userId: result.subject.startsWith('user_') ? result.subject : null,
+ orgId: result.subject.startsWith('org_') ? result.subject : null,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -267,14 +270,18 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ machineId: result.subject,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
+ const result = verificationResult as IdPOAuthAccessToken;
  return {
  ...baseObject,
  tokenType,
- scopes: verificationResult.scopes,
- } as AuthenticatedMachineObject<T>;
+ scopes: result.scopes,
+ userId: result.subject,
+ clientId: result.clientId,
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -304,6 +311,9 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ userId: null,
+ orgId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -312,13 +322,18 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ machineId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
  ...baseObject,
  tokenType,
- } as UnauthenticatedMachineObject<T>;
+ scopes: null,
+ userId: null,
+ clientId: null,
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -406,7 +421,7 @@ export const getAuthObjectFromJwt = (
  *
  * @example
  * // Accept 'api_key' or 'machine_token'
- * const authObject = { tokenType: 'machine_token', id: 'mt_123' };
+ * const authObject = { tokenType: 'machine_token', id: 'm2m_123' };
  * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: ['api_key', 'machine_token'] });
  * // result will be the original authObject (since tokenType matches one in the array)
  *

packages/backend/src/tokens/verify.ts

@@ -214,12 +214,12 @@ async function verifyMachineToken(
 }
 
 async function verifyOAuthToken(
-secret: string,
+accessToken: string,
  options: VerifyTokenOptions,
 ): Promise<MachineTokenReturnType<IdPOAuthAccessToken, MachineTokenVerificationError>> {
  try {
  const client = createBackendApiClient(options);
- const verifiedToken = await client.idPOAuthAccessToken.verifySecret(secret);
+ const verifiedToken = await client.idPOAuthAccessToken.verifyAccessToken(accessToken);
  return { data: verifiedToken, tokenType: TokenType.OAuthToken, errors: undefined };
  } catch (err: any) {
  return handleClerkAPIError(TokenType.OAuthToken, err, 'OAuth token not found');

packages/express/src/__tests__/getAuth.test.ts

@@ -21,18 +21,19 @@ describe('getAuth', () => {
  });
 
  it('returns the actual auth object when its tokenType matches acceptsToken', () => {
- const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', subject: 'api_key_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', userId: 'user_12345', orgId: null });
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('api_key');
  expect(result.id).toBe('ak_1234');
- expect(result.subject).toBe('api_key_1234');
+ expect(result.userId).toBe('user_12345');
+ expect(result.orgId).toBeNull();
  });
 
  it('returns the actual auth object if its tokenType is included in the acceptsToken array', () => {
- const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'mt_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'm2m_1234' });
  const result = getAuth(req, { acceptsToken: ['machine_token', 'api_key'] });
  expect(result.tokenType).toBe('machine_token');
- expect(result.id).toBe('mt_1234');
+ expect(result.id).toBe('m2m_1234');
  expect(result.subject).toBeUndefined();
  });
 
@@ -41,7 +42,7 @@ describe('getAuth', () => {
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('session_token'); // reflects the actual token found
  // Properties specific to authenticated objects should be null or undefined
- // @ts-expect-error - userId is not a property of the unauthenticated object
  expect(result.userId).toBeNull();
+ expect(result.orgId).toBeNull();
  });
 });

.changeset/mean-items-retire.md

@@ -0,0 +1,36 @@
+---
+"@clerk/backend": minor
+---
+
+Improve `subject` property handling for machine auth objects.
+
+Usage:
+
+```ts
+import { createClerkClient } from '@clerk/backend'
+
+const clerkClient = createClerkClient({
+ secretKey: process.env.CLERK_SECRET_KEY,
+ publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+})
+
+const requestState = await clerkClient.authenticateRequest(request, {
+ acceptsToken: 'any',
+})
+
+const authObject = requestState.toAuth()
+
+switch (authObject.tokenType) {
+ case 'api_key':
+ // authObject.userId
+ // authObject.orgId
+ break;
+ case 'machine_token':
+ // authObject.machineId
+ break;
+ case 'oauth_token':
+ // authObject.userId
+ // authObject.clientId
+ break;
+}
+```

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

@@ -5,11 +5,11 @@ import { AbstractAPI } from './AbstractApi';
 const basePath = '/oauth_applications/access_tokens';
 
 export class IdPOAuthAccessTokenApi extends AbstractAPI {
- async verifySecret(secret: string) {
+ async verifyAccessToken(accessToken: string) {
  return this.request<IdPOAuthAccessToken>({
  method: 'POST',
  path: joinPaths(basePath, 'verify'),
- bodyParams: { secret },
+ bodyParams: { access_token: accessToken },
  });
  }
 }

packages/backend/src/fixtures/machine.ts

@@ -37,9 +37,9 @@ export const mockVerificationResults = {
  updatedAt: 1744928754551,
  },
  machine_token: {
- id: 'mt_ey966f1b1xf93586b2debdcadb0b3bd1',
+ id: 'm2m_ey966f1b1xf93586b2debdcadb0b3bd1',
  name: 'my-machine-token',
- subject: 'user_2vYVtestTESTtestTESTtestTESTtest',
+ subject: 'mch_2vYVtestTESTtestTESTtestTESTtest',
  scopes: ['read:foo', 'write:bar'],
  claims: { foo: 'bar' },
  revoked: false,

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -280,13 +280,34 @@ describe('authenticatedMachineObject', () => {
  expect(authObject.has({})).toBe(false);
  });
 
- it('properly initializes properties', () => {
+ it('properly initializes properties (user)', () => {
  const authObject = authenticatedMachineObject('api_key', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('api_key');
- expect(authObject.name).toBe('my-api-key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.orgId).toBeNull();
+ });
+
+ it('properly initializes properties (org)', () => {
+ const authObject = authenticatedMachineObject(
+ 'api_key',
+ token,
+ {
+ ...verificationResult,
+ subject: 'org_2vYVtestTESTtestTESTtestTESTtest',
+ },
+ debugData,
+ );
+ expect(authObject.tokenType).toBe('api_key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBeNull();
+ expect(authObject.orgId).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 
@@ -308,8 +329,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('oauth_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('oauth_token');
+ expect(authObject.id).toBe('oat_2VTWUzvGC5UhdJCNx6xG1D98edc');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.clientId).toBe('client_2VTWUzvGC5UhdJCNx6xG1D98edc');
  });
  });
 
@@ -332,10 +356,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('machine_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('machine_token');
- expect(authObject.name).toBe('my-machine-token');
- expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.machineId).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 });

packages/backend/src/tokens/__tests__/getAuth.test-d.ts

@@ -1,4 +1,4 @@
-import { assertType, expectTypeOf, test } from 'vitest';
+import { expectTypeOf, test } from 'vitest';
 
 import type { AuthObject } from '../authObjects';
 import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
@@ -32,76 +32,18 @@ test('infers the correct AuthObject type for each accepted token type', () => {
  expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
 });
 
-test('verifies correct properties exist for each token type', () => {
- const request = new Request('https://example.com');
-
- // Session token should have userId
- const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
- expectTypeOf(sessionAuth.userId).toMatchTypeOf<string | null>();
-
- // All machine tokens should have id and subject
- const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
- const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
- const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
-
- expectTypeOf(apiKeyAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.subject).toMatchTypeOf<string | null>();
-
- // Only api_key and machine_token should have name and claims
- expectTypeOf(apiKeyAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- expectTypeOf(machineTokenAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- // oauth_token should NOT have name and claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(oauthTokenAuth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(oauthTokenAuth.claims);
-});
-
 test('verifies discriminated union works correctly with acceptsToken: any', () => {
  const request = new Request('https://example.com');
 
  const auth = getAuth(request, { acceptsToken: 'any' });
 
  if (auth.tokenType === 'session_token') {
- // Should be SessionAuthObject - has userId
- expectTypeOf(auth.userId).toMatchTypeOf<string | null>();
- // Should NOT have machine token properties
- // @ts-expect-error session_token does not have id property
- assertType<string | null>(auth.id);
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
  } else if (auth.tokenType === 'api_key') {
- // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error api_key does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
  } else if (auth.tokenType === 'machine_token') {
- // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error machine_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
  } else if (auth.tokenType === 'oauth_token') {
- // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- // Should NOT have name or claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(auth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(auth.claims);
- // Should NOT have session token properties
- // @ts-expect-error oauth_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
  }
 });

packages/backend/src/tokens/__tests__/verify.test.ts

@@ -119,9 +119,9 @@ describe('tokens.verifyMachineAuthToken(token, options)', () => {
  expect(result.errors).toBeUndefined();
 
  const data = result.data as MachineToken;
- expect(data.id).toBe('mt_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(data.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(data.name).toBe('my-machine-token');
- expect(data.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(data.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(data.scopes).toEqual(['read:foo', 'write:bar']);
  expect(data.claims).toEqual({ foo: 'bar' });
  });

packages/backend/src/tokens/authObjects.ts

@@ -11,7 +11,7 @@ import type {
  SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
-import type { APIKey, CreateBackendApiOptions, MachineToken } from '../api';
+import type { APIKey, CreateBackendApiOptions, IdPOAuthAccessToken, MachineToken } from '../api';
 import { createBackendApiClient } from '../api';
 import { isTokenTypeAccepted } from '../internal';
 import type { AuthenticateContext } from './authenticateContext';
@@ -84,22 +84,23 @@ export type SignedOutAuthObject = {
  * While all machine token types share common properties (id, name, subject, etc),
  * this type defines the additional properties that are unique to each token type.
  *
- * @example
- * api_key & machine_token: adds `claims` property
- * oauth_token: adds no additional properties (empty object)
- *
  * @template TAuthenticated - Whether the machine object is authenticated or not
  */
 type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
- api_key: {
- name: TAuthenticated extends true ? string : null;
- claims: TAuthenticated extends true ? Claims | null : null;
- };
+ api_key: TAuthenticated extends true
+ ?
+ | { name: string; claims: Claims | null; userId: string; orgId: null }
+ | { name: string; claims: Claims | null; userId: null; orgId: string }
+ : { name: null; claims: null; userId: null; orgId: null };
  machine_token: {
  name: TAuthenticated extends true ? string : null;
  claims: TAuthenticated extends true ? Claims | null : null;
+ machineId: TAuthenticated extends true ? string : null;
+ };
+ oauth_token: {
+ userId: TAuthenticated extends true ? string : null;
+ clientId: TAuthenticated extends true ? string : null;
  };
- oauth_token: object;
 };
 
 /**
@@ -257,6 +258,8 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ userId: result.subject.startsWith('user_') ? result.subject : null,
+ orgId: result.subject.startsWith('org_') ? result.subject : null,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -267,14 +270,18 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ machineId: result.subject,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
+ const result = verificationResult as IdPOAuthAccessToken;
  return {
  ...baseObject,
  tokenType,
- scopes: verificationResult.scopes,
- } as AuthenticatedMachineObject<T>;
+ scopes: result.scopes,
+ userId: result.subject,
+ clientId: result.clientId,
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -304,6 +311,9 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ userId: null,
+ orgId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -312,13 +322,18 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ machineId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
  ...baseObject,
  tokenType,
- } as UnauthenticatedMachineObject<T>;
+ scopes: null,
+ userId: null,
+ clientId: null,
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -406,7 +421,7 @@ export const getAuthObjectFromJwt = (
  *
  * @example
  * // Accept 'api_key' or 'machine_token'
- * const authObject = { tokenType: 'machine_token', id: 'mt_123' };
+ * const authObject = { tokenType: 'machine_token', id: 'm2m_123' };
  * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: ['api_key', 'machine_token'] });
  * // result will be the original authObject (since tokenType matches one in the array)
  *

packages/backend/src/tokens/verify.ts

@@ -214,12 +214,12 @@ async function verifyMachineToken(
 }
 
 async function verifyOAuthToken(
-secret: string,
+accessToken: string,
  options: VerifyTokenOptions,
 ): Promise<MachineTokenReturnType<IdPOAuthAccessToken, MachineTokenVerificationError>> {
  try {
  const client = createBackendApiClient(options);
- const verifiedToken = await client.idPOAuthAccessToken.verifySecret(secret);
+ const verifiedToken = await client.idPOAuthAccessToken.verifyAccessToken(accessToken);
  return { data: verifiedToken, tokenType: TokenType.OAuthToken, errors: undefined };
  } catch (err: any) {
  return handleClerkAPIError(TokenType.OAuthToken, err, 'OAuth token not found');

packages/express/src/__tests__/getAuth.test.ts

@@ -21,18 +21,19 @@ describe('getAuth', () => {
  });
 
  it('returns the actual auth object when its tokenType matches acceptsToken', () => {
- const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', subject: 'api_key_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', userId: 'user_12345', orgId: null });
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('api_key');
  expect(result.id).toBe('ak_1234');
- expect(result.subject).toBe('api_key_1234');
+ expect(result.userId).toBe('user_12345');
+ expect(result.orgId).toBeNull();
  });
 
  it('returns the actual auth object if its tokenType is included in the acceptsToken array', () => {
- const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'mt_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'm2m_1234' });
  const result = getAuth(req, { acceptsToken: ['machine_token', 'api_key'] });
  expect(result.tokenType).toBe('machine_token');
- expect(result.id).toBe('mt_1234');
+ expect(result.id).toBe('m2m_1234');
  expect(result.subject).toBeUndefined();
  });
 
@@ -41,7 +42,7 @@ describe('getAuth', () => {
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('session_token'); // reflects the actual token found
  // Properties specific to authenticated objects should be null or undefined
- // @ts-expect-error - userId is not a property of the unauthenticated object
  expect(result.userId).toBeNull();
+ expect(result.orgId).toBeNull();
  });
 });

.changeset/mean-items-retire.md

@@ -0,0 +1,36 @@
+---
+"@clerk/backend": minor
+---
+
+Improve `subject` property handling for machine auth objects.
+
+Usage:
+
+```ts
+import { createClerkClient } from '@clerk/backend'
+
+const clerkClient = createClerkClient({
+ secretKey: process.env.CLERK_SECRET_KEY,
+ publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+})
+
+const requestState = await clerkClient.authenticateRequest(request, {
+ acceptsToken: 'any',
+})
+
+const authObject = requestState.toAuth()
+
+switch (authObject.tokenType) {
+ case 'api_key':
+ // authObject.userId
+ // authObject.orgId
+ break;
+ case 'machine_token':
+ // authObject.machineId
+ break;
+ case 'oauth_token':
+ // authObject.userId
+ // authObject.clientId
+ break;
+}
+```

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

@@ -5,11 +5,11 @@ import { AbstractAPI } from './AbstractApi';
 const basePath = '/oauth_applications/access_tokens';
 
 export class IdPOAuthAccessTokenApi extends AbstractAPI {
- async verifySecret(secret: string) {
+ async verifyAccessToken(accessToken: string) {
  return this.request<IdPOAuthAccessToken>({
  method: 'POST',
  path: joinPaths(basePath, 'verify'),
- bodyParams: { secret },
+ bodyParams: { access_token: accessToken },
  });
  }
 }

packages/backend/src/fixtures/machine.ts

@@ -37,9 +37,9 @@ export const mockVerificationResults = {
  updatedAt: 1744928754551,
  },
  machine_token: {
- id: 'mt_ey966f1b1xf93586b2debdcadb0b3bd1',
+ id: 'm2m_ey966f1b1xf93586b2debdcadb0b3bd1',
  name: 'my-machine-token',
- subject: 'user_2vYVtestTESTtestTESTtestTESTtest',
+ subject: 'mch_2vYVtestTESTtestTESTtestTESTtest',
  scopes: ['read:foo', 'write:bar'],
  claims: { foo: 'bar' },
  revoked: false,

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -280,13 +280,34 @@ describe('authenticatedMachineObject', () => {
  expect(authObject.has({})).toBe(false);
  });
 
- it('properly initializes properties', () => {
+ it('properly initializes properties (user)', () => {
  const authObject = authenticatedMachineObject('api_key', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('api_key');
- expect(authObject.name).toBe('my-api-key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.orgId).toBeNull();
+ });
+
+ it('properly initializes properties (org)', () => {
+ const authObject = authenticatedMachineObject(
+ 'api_key',
+ token,
+ {
+ ...verificationResult,
+ subject: 'org_2vYVtestTESTtestTESTtestTESTtest',
+ },
+ debugData,
+ );
+ expect(authObject.tokenType).toBe('api_key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBeNull();
+ expect(authObject.orgId).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 
@@ -308,8 +329,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('oauth_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('oauth_token');
+ expect(authObject.id).toBe('oat_2VTWUzvGC5UhdJCNx6xG1D98edc');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.clientId).toBe('client_2VTWUzvGC5UhdJCNx6xG1D98edc');
  });
  });
 
@@ -332,10 +356,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('machine_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('machine_token');
- expect(authObject.name).toBe('my-machine-token');
- expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.machineId).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 });

packages/backend/src/tokens/__tests__/getAuth.test-d.ts

@@ -1,4 +1,4 @@
-import { assertType, expectTypeOf, test } from 'vitest';
+import { expectTypeOf, test } from 'vitest';
 
 import type { AuthObject } from '../authObjects';
 import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
@@ -32,76 +32,18 @@ test('infers the correct AuthObject type for each accepted token type', () => {
  expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
 });
 
-test('verifies correct properties exist for each token type', () => {
- const request = new Request('https://example.com');
-
- // Session token should have userId
- const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
- expectTypeOf(sessionAuth.userId).toMatchTypeOf<string | null>();
-
- // All machine tokens should have id and subject
- const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
- const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
- const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
-
- expectTypeOf(apiKeyAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.subject).toMatchTypeOf<string | null>();
-
- // Only api_key and machine_token should have name and claims
- expectTypeOf(apiKeyAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- expectTypeOf(machineTokenAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- // oauth_token should NOT have name and claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(oauthTokenAuth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(oauthTokenAuth.claims);
-});
-
 test('verifies discriminated union works correctly with acceptsToken: any', () => {
  const request = new Request('https://example.com');
 
  const auth = getAuth(request, { acceptsToken: 'any' });
 
  if (auth.tokenType === 'session_token') {
- // Should be SessionAuthObject - has userId
- expectTypeOf(auth.userId).toMatchTypeOf<string | null>();
- // Should NOT have machine token properties
- // @ts-expect-error session_token does not have id property
- assertType<string | null>(auth.id);
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
  } else if (auth.tokenType === 'api_key') {
- // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error api_key does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
  } else if (auth.tokenType === 'machine_token') {
- // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error machine_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
  } else if (auth.tokenType === 'oauth_token') {
- // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- // Should NOT have name or claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(auth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(auth.claims);
- // Should NOT have session token properties
- // @ts-expect-error oauth_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
  }
 });

packages/backend/src/tokens/__tests__/verify.test.ts

@@ -119,9 +119,9 @@ describe('tokens.verifyMachineAuthToken(token, options)', () => {
  expect(result.errors).toBeUndefined();
 
  const data = result.data as MachineToken;
- expect(data.id).toBe('mt_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(data.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(data.name).toBe('my-machine-token');
- expect(data.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(data.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(data.scopes).toEqual(['read:foo', 'write:bar']);
  expect(data.claims).toEqual({ foo: 'bar' });
  });

packages/backend/src/tokens/authObjects.ts

@@ -11,7 +11,7 @@ import type {
  SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
-import type { APIKey, CreateBackendApiOptions, MachineToken } from '../api';
+import type { APIKey, CreateBackendApiOptions, IdPOAuthAccessToken, MachineToken } from '../api';
 import { createBackendApiClient } from '../api';
 import { isTokenTypeAccepted } from '../internal';
 import type { AuthenticateContext } from './authenticateContext';
@@ -84,22 +84,23 @@ export type SignedOutAuthObject = {
  * While all machine token types share common properties (id, name, subject, etc),
  * this type defines the additional properties that are unique to each token type.
  *
- * @example
- * api_key & machine_token: adds `claims` property
- * oauth_token: adds no additional properties (empty object)
- *
  * @template TAuthenticated - Whether the machine object is authenticated or not
  */
 type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
- api_key: {
- name: TAuthenticated extends true ? string : null;
- claims: TAuthenticated extends true ? Claims | null : null;
- };
+ api_key: TAuthenticated extends true
+ ?
+ | { name: string; claims: Claims | null; userId: string; orgId: null }
+ | { name: string; claims: Claims | null; userId: null; orgId: string }
+ : { name: null; claims: null; userId: null; orgId: null };
  machine_token: {
  name: TAuthenticated extends true ? string : null;
  claims: TAuthenticated extends true ? Claims | null : null;
+ machineId: TAuthenticated extends true ? string : null;
+ };
+ oauth_token: {
+ userId: TAuthenticated extends true ? string : null;
+ clientId: TAuthenticated extends true ? string : null;
  };
- oauth_token: object;
 };
 
 /**
@@ -257,6 +258,8 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ userId: result.subject.startsWith('user_') ? result.subject : null,
+ orgId: result.subject.startsWith('org_') ? result.subject : null,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -267,14 +270,18 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ machineId: result.subject,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
+ const result = verificationResult as IdPOAuthAccessToken;
  return {
  ...baseObject,
  tokenType,
- scopes: verificationResult.scopes,
- } as AuthenticatedMachineObject<T>;
+ scopes: result.scopes,
+ userId: result.subject,
+ clientId: result.clientId,
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -304,6 +311,9 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ userId: null,
+ orgId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -312,13 +322,18 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ machineId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
  ...baseObject,
  tokenType,
- } as UnauthenticatedMachineObject<T>;
+ scopes: null,
+ userId: null,
+ clientId: null,
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -406,7 +421,7 @@ export const getAuthObjectFromJwt = (
  *
  * @example
  * // Accept 'api_key' or 'machine_token'
- * const authObject = { tokenType: 'machine_token', id: 'mt_123' };
+ * const authObject = { tokenType: 'machine_token', id: 'm2m_123' };
  * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: ['api_key', 'machine_token'] });
  * // result will be the original authObject (since tokenType matches one in the array)
  *

packages/backend/src/tokens/verify.ts

@@ -214,12 +214,12 @@ async function verifyMachineToken(
 }
 
 async function verifyOAuthToken(
-secret: string,
+accessToken: string,
  options: VerifyTokenOptions,
 ): Promise<MachineTokenReturnType<IdPOAuthAccessToken, MachineTokenVerificationError>> {
  try {
  const client = createBackendApiClient(options);
- const verifiedToken = await client.idPOAuthAccessToken.verifySecret(secret);
+ const verifiedToken = await client.idPOAuthAccessToken.verifyAccessToken(accessToken);
  return { data: verifiedToken, tokenType: TokenType.OAuthToken, errors: undefined };
  } catch (err: any) {
  return handleClerkAPIError(TokenType.OAuthToken, err, 'OAuth token not found');

packages/express/src/__tests__/getAuth.test.ts

@@ -21,18 +21,19 @@ describe('getAuth', () => {
  });
 
  it('returns the actual auth object when its tokenType matches acceptsToken', () => {
- const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', subject: 'api_key_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', userId: 'user_12345', orgId: null });
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('api_key');
  expect(result.id).toBe('ak_1234');
- expect(result.subject).toBe('api_key_1234');
+ expect(result.userId).toBe('user_12345');
+ expect(result.orgId).toBeNull();
  });
 
  it('returns the actual auth object if its tokenType is included in the acceptsToken array', () => {
- const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'mt_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'm2m_1234' });
  const result = getAuth(req, { acceptsToken: ['machine_token', 'api_key'] });
  expect(result.tokenType).toBe('machine_token');
- expect(result.id).toBe('mt_1234');
+ expect(result.id).toBe('m2m_1234');
  expect(result.subject).toBeUndefined();
  });
 
@@ -41,7 +42,7 @@ describe('getAuth', () => {
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('session_token'); // reflects the actual token found
  // Properties specific to authenticated objects should be null or undefined
- // @ts-expect-error - userId is not a property of the unauthenticated object
  expect(result.userId).toBeNull();
+ expect(result.orgId).toBeNull();
  });
 });

.changeset/mean-items-retire.md

@@ -0,0 +1,36 @@
+---
+"@clerk/backend": minor
+---
+
+Improve `subject` property handling for machine auth objects.
+
+Usage:
+
+```ts
+import { createClerkClient } from '@clerk/backend'
+
+const clerkClient = createClerkClient({
+ secretKey: process.env.CLERK_SECRET_KEY,
+ publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+})
+
+const requestState = await clerkClient.authenticateRequest(request, {
+ acceptsToken: 'any',
+})
+
+const authObject = requestState.toAuth()
+
+switch (authObject.tokenType) {
+ case 'api_key':
+ // authObject.userId
+ // authObject.orgId
+ break;
+ case 'machine_token':
+ // authObject.machineId
+ break;
+ case 'oauth_token':
+ // authObject.userId
+ // authObject.clientId
+ break;
+}
+```

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

@@ -5,11 +5,11 @@ import { AbstractAPI } from './AbstractApi';
 const basePath = '/oauth_applications/access_tokens';
 
 export class IdPOAuthAccessTokenApi extends AbstractAPI {
- async verifySecret(secret: string) {
+ async verifyAccessToken(accessToken: string) {
  return this.request<IdPOAuthAccessToken>({
  method: 'POST',
  path: joinPaths(basePath, 'verify'),
- bodyParams: { secret },
+ bodyParams: { access_token: accessToken },
  });
  }
 }

packages/backend/src/fixtures/machine.ts

@@ -37,9 +37,9 @@ export const mockVerificationResults = {
  updatedAt: 1744928754551,
  },
  machine_token: {
- id: 'mt_ey966f1b1xf93586b2debdcadb0b3bd1',
+ id: 'm2m_ey966f1b1xf93586b2debdcadb0b3bd1',
  name: 'my-machine-token',
- subject: 'user_2vYVtestTESTtestTESTtestTESTtest',
+ subject: 'mch_2vYVtestTESTtestTESTtestTESTtest',
  scopes: ['read:foo', 'write:bar'],
  claims: { foo: 'bar' },
  revoked: false,

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -280,13 +280,34 @@ describe('authenticatedMachineObject', () => {
  expect(authObject.has({})).toBe(false);
  });
 
- it('properly initializes properties', () => {
+ it('properly initializes properties (user)', () => {
  const authObject = authenticatedMachineObject('api_key', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('api_key');
- expect(authObject.name).toBe('my-api-key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.orgId).toBeNull();
+ });
+
+ it('properly initializes properties (org)', () => {
+ const authObject = authenticatedMachineObject(
+ 'api_key',
+ token,
+ {
+ ...verificationResult,
+ subject: 'org_2vYVtestTESTtestTESTtestTESTtest',
+ },
+ debugData,
+ );
+ expect(authObject.tokenType).toBe('api_key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBeNull();
+ expect(authObject.orgId).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 
@@ -308,8 +329,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('oauth_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('oauth_token');
+ expect(authObject.id).toBe('oat_2VTWUzvGC5UhdJCNx6xG1D98edc');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.clientId).toBe('client_2VTWUzvGC5UhdJCNx6xG1D98edc');
  });
  });
 
@@ -332,10 +356,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('machine_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('machine_token');
- expect(authObject.name).toBe('my-machine-token');
- expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.machineId).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 });

packages/backend/src/tokens/__tests__/getAuth.test-d.ts

@@ -1,4 +1,4 @@
-import { assertType, expectTypeOf, test } from 'vitest';
+import { expectTypeOf, test } from 'vitest';
 
 import type { AuthObject } from '../authObjects';
 import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
@@ -32,76 +32,18 @@ test('infers the correct AuthObject type for each accepted token type', () => {
  expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
 });
 
-test('verifies correct properties exist for each token type', () => {
- const request = new Request('https://example.com');
-
- // Session token should have userId
- const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
- expectTypeOf(sessionAuth.userId).toMatchTypeOf<string | null>();
-
- // All machine tokens should have id and subject
- const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
- const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
- const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
-
- expectTypeOf(apiKeyAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.subject).toMatchTypeOf<string | null>();
-
- // Only api_key and machine_token should have name and claims
- expectTypeOf(apiKeyAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- expectTypeOf(machineTokenAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- // oauth_token should NOT have name and claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(oauthTokenAuth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(oauthTokenAuth.claims);
-});
-
 test('verifies discriminated union works correctly with acceptsToken: any', () => {
  const request = new Request('https://example.com');
 
  const auth = getAuth(request, { acceptsToken: 'any' });
 
  if (auth.tokenType === 'session_token') {
- // Should be SessionAuthObject - has userId
- expectTypeOf(auth.userId).toMatchTypeOf<string | null>();
- // Should NOT have machine token properties
- // @ts-expect-error session_token does not have id property
- assertType<string | null>(auth.id);
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
  } else if (auth.tokenType === 'api_key') {
- // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error api_key does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
  } else if (auth.tokenType === 'machine_token') {
- // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error machine_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
  } else if (auth.tokenType === 'oauth_token') {
- // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- // Should NOT have name or claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(auth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(auth.claims);
- // Should NOT have session token properties
- // @ts-expect-error oauth_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
  }
 });

packages/backend/src/tokens/__tests__/verify.test.ts

@@ -119,9 +119,9 @@ describe('tokens.verifyMachineAuthToken(token, options)', () => {
  expect(result.errors).toBeUndefined();
 
  const data = result.data as MachineToken;
- expect(data.id).toBe('mt_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(data.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(data.name).toBe('my-machine-token');
- expect(data.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(data.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(data.scopes).toEqual(['read:foo', 'write:bar']);
  expect(data.claims).toEqual({ foo: 'bar' });
  });

packages/backend/src/tokens/authObjects.ts

@@ -11,7 +11,7 @@ import type {
  SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
-import type { APIKey, CreateBackendApiOptions, MachineToken } from '../api';
+import type { APIKey, CreateBackendApiOptions, IdPOAuthAccessToken, MachineToken } from '../api';
 import { createBackendApiClient } from '../api';
 import { isTokenTypeAccepted } from '../internal';
 import type { AuthenticateContext } from './authenticateContext';
@@ -84,22 +84,23 @@ export type SignedOutAuthObject = {
  * While all machine token types share common properties (id, name, subject, etc),
  * this type defines the additional properties that are unique to each token type.
  *
- * @example
- * api_key & machine_token: adds `claims` property
- * oauth_token: adds no additional properties (empty object)
- *
  * @template TAuthenticated - Whether the machine object is authenticated or not
  */
 type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
- api_key: {
- name: TAuthenticated extends true ? string : null;
- claims: TAuthenticated extends true ? Claims | null : null;
- };
+ api_key: TAuthenticated extends true
+ ?
+ | { name: string; claims: Claims | null; userId: string; orgId: null }
+ | { name: string; claims: Claims | null; userId: null; orgId: string }
+ : { name: null; claims: null; userId: null; orgId: null };
  machine_token: {
  name: TAuthenticated extends true ? string : null;
  claims: TAuthenticated extends true ? Claims | null : null;
+ machineId: TAuthenticated extends true ? string : null;
+ };
+ oauth_token: {
+ userId: TAuthenticated extends true ? string : null;
+ clientId: TAuthenticated extends true ? string : null;
  };
- oauth_token: object;
 };
 
 /**
@@ -257,6 +258,8 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ userId: result.subject.startsWith('user_') ? result.subject : null,
+ orgId: result.subject.startsWith('org_') ? result.subject : null,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -267,14 +270,18 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ machineId: result.subject,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
+ const result = verificationResult as IdPOAuthAccessToken;
  return {
  ...baseObject,
  tokenType,
- scopes: verificationResult.scopes,
- } as AuthenticatedMachineObject<T>;
+ scopes: result.scopes,
+ userId: result.subject,
+ clientId: result.clientId,
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -304,6 +311,9 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ userId: null,
+ orgId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -312,13 +322,18 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ machineId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
  ...baseObject,
  tokenType,
- } as UnauthenticatedMachineObject<T>;
+ scopes: null,
+ userId: null,
+ clientId: null,
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -406,7 +421,7 @@ export const getAuthObjectFromJwt = (
  *
  * @example
  * // Accept 'api_key' or 'machine_token'
- * const authObject = { tokenType: 'machine_token', id: 'mt_123' };
+ * const authObject = { tokenType: 'machine_token', id: 'm2m_123' };
  * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: ['api_key', 'machine_token'] });
  * // result will be the original authObject (since tokenType matches one in the array)
  *

packages/backend/src/tokens/verify.ts

@@ -214,12 +214,12 @@ async function verifyMachineToken(
 }
 
 async function verifyOAuthToken(
-secret: string,
+accessToken: string,
  options: VerifyTokenOptions,
 ): Promise<MachineTokenReturnType<IdPOAuthAccessToken, MachineTokenVerificationError>> {
  try {
  const client = createBackendApiClient(options);
- const verifiedToken = await client.idPOAuthAccessToken.verifySecret(secret);
+ const verifiedToken = await client.idPOAuthAccessToken.verifyAccessToken(accessToken);
  return { data: verifiedToken, tokenType: TokenType.OAuthToken, errors: undefined };
  } catch (err: any) {
  return handleClerkAPIError(TokenType.OAuthToken, err, 'OAuth token not found');

packages/express/src/__tests__/getAuth.test.ts

@@ -21,18 +21,19 @@ describe('getAuth', () => {
  });
 
  it('returns the actual auth object when its tokenType matches acceptsToken', () => {
- const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', subject: 'api_key_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', userId: 'user_12345', orgId: null });
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('api_key');
  expect(result.id).toBe('ak_1234');
- expect(result.subject).toBe('api_key_1234');
+ expect(result.userId).toBe('user_12345');
+ expect(result.orgId).toBeNull();
  });
 
  it('returns the actual auth object if its tokenType is included in the acceptsToken array', () => {
- const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'mt_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'm2m_1234' });
  const result = getAuth(req, { acceptsToken: ['machine_token', 'api_key'] });
  expect(result.tokenType).toBe('machine_token');
- expect(result.id).toBe('mt_1234');
+ expect(result.id).toBe('m2m_1234');
  expect(result.subject).toBeUndefined();
  });
 
@@ -41,7 +42,7 @@ describe('getAuth', () => {
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('session_token'); // reflects the actual token found
  // Properties specific to authenticated objects should be null or undefined
- // @ts-expect-error - userId is not a property of the unauthenticated object
  expect(result.userId).toBeNull();
+ expect(result.orgId).toBeNull();
  });
 });

.changeset/mean-items-retire.md

@@ -0,0 +1,36 @@
+---
+"@clerk/backend": minor
+---
+
+Improve `subject` property handling for machine auth objects.
+
+Usage:
+
+```ts
+import { createClerkClient } from '@clerk/backend'
+
+const clerkClient = createClerkClient({
+ secretKey: process.env.CLERK_SECRET_KEY,
+ publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+})
+
+const requestState = await clerkClient.authenticateRequest(request, {
+ acceptsToken: 'any',
+})
+
+const authObject = requestState.toAuth()
+
+switch (authObject.tokenType) {
+ case 'api_key':
+ // authObject.userId
+ // authObject.orgId
+ break;
+ case 'machine_token':
+ // authObject.machineId
+ break;
+ case 'oauth_token':
+ // authObject.userId
+ // authObject.clientId
+ break;
+}
+```

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

@@ -5,11 +5,11 @@ import { AbstractAPI } from './AbstractApi';
 const basePath = '/oauth_applications/access_tokens';
 
 export class IdPOAuthAccessTokenApi extends AbstractAPI {
- async verifySecret(secret: string) {
+ async verifyAccessToken(accessToken: string) {
  return this.request<IdPOAuthAccessToken>({
  method: 'POST',
  path: joinPaths(basePath, 'verify'),
- bodyParams: { secret },
+ bodyParams: { access_token: accessToken },
  });
  }
 }

packages/backend/src/fixtures/machine.ts

@@ -37,9 +37,9 @@ export const mockVerificationResults = {
  updatedAt: 1744928754551,
  },
  machine_token: {
- id: 'mt_ey966f1b1xf93586b2debdcadb0b3bd1',
+ id: 'm2m_ey966f1b1xf93586b2debdcadb0b3bd1',
  name: 'my-machine-token',
- subject: 'user_2vYVtestTESTtestTESTtestTESTtest',
+ subject: 'mch_2vYVtestTESTtestTESTtestTESTtest',
  scopes: ['read:foo', 'write:bar'],
  claims: { foo: 'bar' },
  revoked: false,

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -280,13 +280,34 @@ describe('authenticatedMachineObject', () => {
  expect(authObject.has({})).toBe(false);
  });
 
- it('properly initializes properties', () => {
+ it('properly initializes properties (user)', () => {
  const authObject = authenticatedMachineObject('api_key', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('api_key');
- expect(authObject.name).toBe('my-api-key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.orgId).toBeNull();
+ });
+
+ it('properly initializes properties (org)', () => {
+ const authObject = authenticatedMachineObject(
+ 'api_key',
+ token,
+ {
+ ...verificationResult,
+ subject: 'org_2vYVtestTESTtestTESTtestTESTtest',
+ },
+ debugData,
+ );
+ expect(authObject.tokenType).toBe('api_key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBeNull();
+ expect(authObject.orgId).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 
@@ -308,8 +329,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('oauth_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('oauth_token');
+ expect(authObject.id).toBe('oat_2VTWUzvGC5UhdJCNx6xG1D98edc');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.clientId).toBe('client_2VTWUzvGC5UhdJCNx6xG1D98edc');
  });
  });
 
@@ -332,10 +356,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('machine_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('machine_token');
- expect(authObject.name).toBe('my-machine-token');
- expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.machineId).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 });

packages/backend/src/tokens/__tests__/getAuth.test-d.ts

@@ -1,4 +1,4 @@
-import { assertType, expectTypeOf, test } from 'vitest';
+import { expectTypeOf, test } from 'vitest';
 
 import type { AuthObject } from '../authObjects';
 import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
@@ -32,76 +32,18 @@ test('infers the correct AuthObject type for each accepted token type', () => {
  expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
 });
 
-test('verifies correct properties exist for each token type', () => {
- const request = new Request('https://example.com');
-
- // Session token should have userId
- const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
- expectTypeOf(sessionAuth.userId).toMatchTypeOf<string | null>();
-
- // All machine tokens should have id and subject
- const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
- const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
- const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
-
- expectTypeOf(apiKeyAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.subject).toMatchTypeOf<string | null>();
-
- // Only api_key and machine_token should have name and claims
- expectTypeOf(apiKeyAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- expectTypeOf(machineTokenAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- // oauth_token should NOT have name and claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(oauthTokenAuth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(oauthTokenAuth.claims);
-});
-
 test('verifies discriminated union works correctly with acceptsToken: any', () => {
  const request = new Request('https://example.com');
 
  const auth = getAuth(request, { acceptsToken: 'any' });
 
  if (auth.tokenType === 'session_token') {
- // Should be SessionAuthObject - has userId
- expectTypeOf(auth.userId).toMatchTypeOf<string | null>();
- // Should NOT have machine token properties
- // @ts-expect-error session_token does not have id property
- assertType<string | null>(auth.id);
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
  } else if (auth.tokenType === 'api_key') {
- // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error api_key does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
  } else if (auth.tokenType === 'machine_token') {
- // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error machine_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
  } else if (auth.tokenType === 'oauth_token') {
- // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- // Should NOT have name or claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(auth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(auth.claims);
- // Should NOT have session token properties
- // @ts-expect-error oauth_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
  }
 });

packages/backend/src/tokens/__tests__/verify.test.ts

@@ -119,9 +119,9 @@ describe('tokens.verifyMachineAuthToken(token, options)', () => {
  expect(result.errors).toBeUndefined();
 
  const data = result.data as MachineToken;
- expect(data.id).toBe('mt_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(data.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(data.name).toBe('my-machine-token');
- expect(data.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(data.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(data.scopes).toEqual(['read:foo', 'write:bar']);
  expect(data.claims).toEqual({ foo: 'bar' });
  });

packages/backend/src/tokens/authObjects.ts

@@ -11,7 +11,7 @@ import type {
  SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
-import type { APIKey, CreateBackendApiOptions, MachineToken } from '../api';
+import type { APIKey, CreateBackendApiOptions, IdPOAuthAccessToken, MachineToken } from '../api';
 import { createBackendApiClient } from '../api';
 import { isTokenTypeAccepted } from '../internal';
 import type { AuthenticateContext } from './authenticateContext';
@@ -84,22 +84,23 @@ export type SignedOutAuthObject = {
  * While all machine token types share common properties (id, name, subject, etc),
  * this type defines the additional properties that are unique to each token type.
  *
- * @example
- * api_key & machine_token: adds `claims` property
- * oauth_token: adds no additional properties (empty object)
- *
  * @template TAuthenticated - Whether the machine object is authenticated or not
  */
 type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
- api_key: {
- name: TAuthenticated extends true ? string : null;
- claims: TAuthenticated extends true ? Claims | null : null;
- };
+ api_key: TAuthenticated extends true
+ ?
+ | { name: string; claims: Claims | null; userId: string; orgId: null }
+ | { name: string; claims: Claims | null; userId: null; orgId: string }
+ : { name: null; claims: null; userId: null; orgId: null };
  machine_token: {
  name: TAuthenticated extends true ? string : null;
  claims: TAuthenticated extends true ? Claims | null : null;
+ machineId: TAuthenticated extends true ? string : null;
+ };
+ oauth_token: {
+ userId: TAuthenticated extends true ? string : null;
+ clientId: TAuthenticated extends true ? string : null;
  };
- oauth_token: object;
 };
 
 /**
@@ -257,6 +258,8 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ userId: result.subject.startsWith('user_') ? result.subject : null,
+ orgId: result.subject.startsWith('org_') ? result.subject : null,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -267,14 +270,18 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ machineId: result.subject,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
+ const result = verificationResult as IdPOAuthAccessToken;
  return {
  ...baseObject,
  tokenType,
- scopes: verificationResult.scopes,
- } as AuthenticatedMachineObject<T>;
+ scopes: result.scopes,
+ userId: result.subject,
+ clientId: result.clientId,
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -304,6 +311,9 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ userId: null,
+ orgId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -312,13 +322,18 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ machineId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
  ...baseObject,
  tokenType,
- } as UnauthenticatedMachineObject<T>;
+ scopes: null,
+ userId: null,
+ clientId: null,
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -406,7 +421,7 @@ export const getAuthObjectFromJwt = (
  *
  * @example
  * // Accept 'api_key' or 'machine_token'
- * const authObject = { tokenType: 'machine_token', id: 'mt_123' };
+ * const authObject = { tokenType: 'machine_token', id: 'm2m_123' };
  * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: ['api_key', 'machine_token'] });
  * // result will be the original authObject (since tokenType matches one in the array)
  *

packages/backend/src/tokens/verify.ts

@@ -214,12 +214,12 @@ async function verifyMachineToken(
 }
 
 async function verifyOAuthToken(
-secret: string,
+accessToken: string,
  options: VerifyTokenOptions,
 ): Promise<MachineTokenReturnType<IdPOAuthAccessToken, MachineTokenVerificationError>> {
  try {
  const client = createBackendApiClient(options);
- const verifiedToken = await client.idPOAuthAccessToken.verifySecret(secret);
+ const verifiedToken = await client.idPOAuthAccessToken.verifyAccessToken(accessToken);
  return { data: verifiedToken, tokenType: TokenType.OAuthToken, errors: undefined };
  } catch (err: any) {
  return handleClerkAPIError(TokenType.OAuthToken, err, 'OAuth token not found');

packages/express/src/__tests__/getAuth.test.ts

@@ -21,18 +21,19 @@ describe('getAuth', () => {
  });
 
  it('returns the actual auth object when its tokenType matches acceptsToken', () => {
- const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', subject: 'api_key_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', userId: 'user_12345', orgId: null });
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('api_key');
  expect(result.id).toBe('ak_1234');
- expect(result.subject).toBe('api_key_1234');
+ expect(result.userId).toBe('user_12345');
+ expect(result.orgId).toBeNull();
  });
 
  it('returns the actual auth object if its tokenType is included in the acceptsToken array', () => {
- const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'mt_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'm2m_1234' });
  const result = getAuth(req, { acceptsToken: ['machine_token', 'api_key'] });
  expect(result.tokenType).toBe('machine_token');
- expect(result.id).toBe('mt_1234');
+ expect(result.id).toBe('m2m_1234');
  expect(result.subject).toBeUndefined();
  });
 
@@ -41,7 +42,7 @@ describe('getAuth', () => {
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('session_token'); // reflects the actual token found
  // Properties specific to authenticated objects should be null or undefined
- // @ts-expect-error - userId is not a property of the unauthenticated object
  expect(result.userId).toBeNull();
+ expect(result.orgId).toBeNull();
  });
 });

.changeset/mean-items-retire.md

@@ -0,0 +1,36 @@
+---
+"@clerk/backend": minor
+---
+
+Improve `subject` property handling for machine auth objects.
+
+Usage:
+
+```ts
+import { createClerkClient } from '@clerk/backend'
+
+const clerkClient = createClerkClient({
+ secretKey: process.env.CLERK_SECRET_KEY,
+ publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+})
+
+const requestState = await clerkClient.authenticateRequest(request, {
+ acceptsToken: 'any',
+})
+
+const authObject = requestState.toAuth()
+
+switch (authObject.tokenType) {
+ case 'api_key':
+ // authObject.userId
+ // authObject.orgId
+ break;
+ case 'machine_token':
+ // authObject.machineId
+ break;
+ case 'oauth_token':
+ // authObject.userId
+ // authObject.clientId
+ break;
+}
+```

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

@@ -5,11 +5,11 @@ import { AbstractAPI } from './AbstractApi';
 const basePath = '/oauth_applications/access_tokens';
 
 export class IdPOAuthAccessTokenApi extends AbstractAPI {
- async verifySecret(secret: string) {
+ async verifyAccessToken(accessToken: string) {
  return this.request<IdPOAuthAccessToken>({
  method: 'POST',
  path: joinPaths(basePath, 'verify'),
- bodyParams: { secret },
+ bodyParams: { access_token: accessToken },
  });
  }
 }

packages/backend/src/fixtures/machine.ts

@@ -37,9 +37,9 @@ export const mockVerificationResults = {
  updatedAt: 1744928754551,
  },
  machine_token: {
- id: 'mt_ey966f1b1xf93586b2debdcadb0b3bd1',
+ id: 'm2m_ey966f1b1xf93586b2debdcadb0b3bd1',
  name: 'my-machine-token',
- subject: 'user_2vYVtestTESTtestTESTtestTESTtest',
+ subject: 'mch_2vYVtestTESTtestTESTtestTESTtest',
  scopes: ['read:foo', 'write:bar'],
  claims: { foo: 'bar' },
  revoked: false,

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -280,13 +280,34 @@ describe('authenticatedMachineObject', () => {
  expect(authObject.has({})).toBe(false);
  });
 
- it('properly initializes properties', () => {
+ it('properly initializes properties (user)', () => {
  const authObject = authenticatedMachineObject('api_key', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('api_key');
- expect(authObject.name).toBe('my-api-key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.orgId).toBeNull();
+ });
+
+ it('properly initializes properties (org)', () => {
+ const authObject = authenticatedMachineObject(
+ 'api_key',
+ token,
+ {
+ ...verificationResult,
+ subject: 'org_2vYVtestTESTtestTESTtestTESTtest',
+ },
+ debugData,
+ );
+ expect(authObject.tokenType).toBe('api_key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBeNull();
+ expect(authObject.orgId).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 
@@ -308,8 +329,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('oauth_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('oauth_token');
+ expect(authObject.id).toBe('oat_2VTWUzvGC5UhdJCNx6xG1D98edc');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.clientId).toBe('client_2VTWUzvGC5UhdJCNx6xG1D98edc');
  });
  });
 
@@ -332,10 +356,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('machine_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('machine_token');
- expect(authObject.name).toBe('my-machine-token');
- expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.machineId).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 });

packages/backend/src/tokens/__tests__/getAuth.test-d.ts

@@ -1,4 +1,4 @@
-import { assertType, expectTypeOf, test } from 'vitest';
+import { expectTypeOf, test } from 'vitest';
 
 import type { AuthObject } from '../authObjects';
 import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
@@ -32,76 +32,18 @@ test('infers the correct AuthObject type for each accepted token type', () => {
  expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
 });
 
-test('verifies correct properties exist for each token type', () => {
- const request = new Request('https://example.com');
-
- // Session token should have userId
- const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
- expectTypeOf(sessionAuth.userId).toMatchTypeOf<string | null>();
-
- // All machine tokens should have id and subject
- const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
- const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
- const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
-
- expectTypeOf(apiKeyAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.subject).toMatchTypeOf<string | null>();
-
- // Only api_key and machine_token should have name and claims
- expectTypeOf(apiKeyAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- expectTypeOf(machineTokenAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- // oauth_token should NOT have name and claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(oauthTokenAuth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(oauthTokenAuth.claims);
-});
-
 test('verifies discriminated union works correctly with acceptsToken: any', () => {
  const request = new Request('https://example.com');
 
  const auth = getAuth(request, { acceptsToken: 'any' });
 
  if (auth.tokenType === 'session_token') {
- // Should be SessionAuthObject - has userId
- expectTypeOf(auth.userId).toMatchTypeOf<string | null>();
- // Should NOT have machine token properties
- // @ts-expect-error session_token does not have id property
- assertType<string | null>(auth.id);
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
  } else if (auth.tokenType === 'api_key') {
- // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error api_key does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
  } else if (auth.tokenType === 'machine_token') {
- // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error machine_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
  } else if (auth.tokenType === 'oauth_token') {
- // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- // Should NOT have name or claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(auth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(auth.claims);
- // Should NOT have session token properties
- // @ts-expect-error oauth_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
  }
 });

packages/backend/src/tokens/__tests__/verify.test.ts

@@ -119,9 +119,9 @@ describe('tokens.verifyMachineAuthToken(token, options)', () => {
  expect(result.errors).toBeUndefined();
 
  const data = result.data as MachineToken;
- expect(data.id).toBe('mt_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(data.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(data.name).toBe('my-machine-token');
- expect(data.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(data.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(data.scopes).toEqual(['read:foo', 'write:bar']);
  expect(data.claims).toEqual({ foo: 'bar' });
  });

packages/backend/src/tokens/authObjects.ts

@@ -11,7 +11,7 @@ import type {
  SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
-import type { APIKey, CreateBackendApiOptions, MachineToken } from '../api';
+import type { APIKey, CreateBackendApiOptions, IdPOAuthAccessToken, MachineToken } from '../api';
 import { createBackendApiClient } from '../api';
 import { isTokenTypeAccepted } from '../internal';
 import type { AuthenticateContext } from './authenticateContext';
@@ -84,22 +84,23 @@ export type SignedOutAuthObject = {
  * While all machine token types share common properties (id, name, subject, etc),
  * this type defines the additional properties that are unique to each token type.
  *
- * @example
- * api_key & machine_token: adds `claims` property
- * oauth_token: adds no additional properties (empty object)
- *
  * @template TAuthenticated - Whether the machine object is authenticated or not
  */
 type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
- api_key: {
- name: TAuthenticated extends true ? string : null;
- claims: TAuthenticated extends true ? Claims | null : null;
- };
+ api_key: TAuthenticated extends true
+ ?
+ | { name: string; claims: Claims | null; userId: string; orgId: null }
+ | { name: string; claims: Claims | null; userId: null; orgId: string }
+ : { name: null; claims: null; userId: null; orgId: null };
  machine_token: {
  name: TAuthenticated extends true ? string : null;
  claims: TAuthenticated extends true ? Claims | null : null;
+ machineId: TAuthenticated extends true ? string : null;
+ };
+ oauth_token: {
+ userId: TAuthenticated extends true ? string : null;
+ clientId: TAuthenticated extends true ? string : null;
  };
- oauth_token: object;
 };
 
 /**
@@ -257,6 +258,8 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ userId: result.subject.startsWith('user_') ? result.subject : null,
+ orgId: result.subject.startsWith('org_') ? result.subject : null,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -267,14 +270,18 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ machineId: result.subject,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
+ const result = verificationResult as IdPOAuthAccessToken;
  return {
  ...baseObject,
  tokenType,
- scopes: verificationResult.scopes,
- } as AuthenticatedMachineObject<T>;
+ scopes: result.scopes,
+ userId: result.subject,
+ clientId: result.clientId,
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -304,6 +311,9 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ userId: null,
+ orgId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -312,13 +322,18 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ machineId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
  ...baseObject,
  tokenType,
- } as UnauthenticatedMachineObject<T>;
+ scopes: null,
+ userId: null,
+ clientId: null,
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -406,7 +421,7 @@ export const getAuthObjectFromJwt = (
  *
  * @example
  * // Accept 'api_key' or 'machine_token'
- * const authObject = { tokenType: 'machine_token', id: 'mt_123' };
+ * const authObject = { tokenType: 'machine_token', id: 'm2m_123' };
  * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: ['api_key', 'machine_token'] });
  * // result will be the original authObject (since tokenType matches one in the array)
  *

packages/backend/src/tokens/verify.ts

@@ -214,12 +214,12 @@ async function verifyMachineToken(
 }
 
 async function verifyOAuthToken(
-secret: string,
+accessToken: string,
  options: VerifyTokenOptions,
 ): Promise<MachineTokenReturnType<IdPOAuthAccessToken, MachineTokenVerificationError>> {
  try {
  const client = createBackendApiClient(options);
- const verifiedToken = await client.idPOAuthAccessToken.verifySecret(secret);
+ const verifiedToken = await client.idPOAuthAccessToken.verifyAccessToken(accessToken);
  return { data: verifiedToken, tokenType: TokenType.OAuthToken, errors: undefined };
  } catch (err: any) {
  return handleClerkAPIError(TokenType.OAuthToken, err, 'OAuth token not found');

packages/express/src/__tests__/getAuth.test.ts

@@ -21,18 +21,19 @@ describe('getAuth', () => {
  });
 
  it('returns the actual auth object when its tokenType matches acceptsToken', () => {
- const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', subject: 'api_key_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', userId: 'user_12345', orgId: null });
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('api_key');
  expect(result.id).toBe('ak_1234');
- expect(result.subject).toBe('api_key_1234');
+ expect(result.userId).toBe('user_12345');
+ expect(result.orgId).toBeNull();
  });
 
  it('returns the actual auth object if its tokenType is included in the acceptsToken array', () => {
- const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'mt_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'm2m_1234' });
  const result = getAuth(req, { acceptsToken: ['machine_token', 'api_key'] });
  expect(result.tokenType).toBe('machine_token');
- expect(result.id).toBe('mt_1234');
+ expect(result.id).toBe('m2m_1234');
  expect(result.subject).toBeUndefined();
  });
 
@@ -41,7 +42,7 @@ describe('getAuth', () => {
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('session_token'); // reflects the actual token found
  // Properties specific to authenticated objects should be null or undefined
- // @ts-expect-error - userId is not a property of the unauthenticated object
  expect(result.userId).toBeNull();
+ expect(result.orgId).toBeNull();
  });
 });

.changeset/mean-items-retire.md

@@ -0,0 +1,36 @@
+---
+"@clerk/backend": minor
+---
+
+Improve `subject` property handling for machine auth objects.
+
+Usage:
+
+```ts
+import { createClerkClient } from '@clerk/backend'
+
+const clerkClient = createClerkClient({
+ secretKey: process.env.CLERK_SECRET_KEY,
+ publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+})
+
+const requestState = await clerkClient.authenticateRequest(request, {
+ acceptsToken: 'any',
+})
+
+const authObject = requestState.toAuth()
+
+switch (authObject.tokenType) {
+ case 'api_key':
+ // authObject.userId
+ // authObject.orgId
+ break;
+ case 'machine_token':
+ // authObject.machineId
+ break;
+ case 'oauth_token':
+ // authObject.userId
+ // authObject.clientId
+ break;
+}
+```

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

@@ -5,11 +5,11 @@ import { AbstractAPI } from './AbstractApi';
 const basePath = '/oauth_applications/access_tokens';
 
 export class IdPOAuthAccessTokenApi extends AbstractAPI {
- async verifySecret(secret: string) {
+ async verifyAccessToken(accessToken: string) {
  return this.request<IdPOAuthAccessToken>({
  method: 'POST',
  path: joinPaths(basePath, 'verify'),
- bodyParams: { secret },
+ bodyParams: { access_token: accessToken },
  });
  }
 }

packages/backend/src/fixtures/machine.ts

@@ -37,9 +37,9 @@ export const mockVerificationResults = {
  updatedAt: 1744928754551,
  },
  machine_token: {
- id: 'mt_ey966f1b1xf93586b2debdcadb0b3bd1',
+ id: 'm2m_ey966f1b1xf93586b2debdcadb0b3bd1',
  name: 'my-machine-token',
- subject: 'user_2vYVtestTESTtestTESTtestTESTtest',
+ subject: 'mch_2vYVtestTESTtestTESTtestTESTtest',
  scopes: ['read:foo', 'write:bar'],
  claims: { foo: 'bar' },
  revoked: false,

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -280,13 +280,34 @@ describe('authenticatedMachineObject', () => {
  expect(authObject.has({})).toBe(false);
  });
 
- it('properly initializes properties', () => {
+ it('properly initializes properties (user)', () => {
  const authObject = authenticatedMachineObject('api_key', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('api_key');
- expect(authObject.name).toBe('my-api-key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.orgId).toBeNull();
+ });
+
+ it('properly initializes properties (org)', () => {
+ const authObject = authenticatedMachineObject(
+ 'api_key',
+ token,
+ {
+ ...verificationResult,
+ subject: 'org_2vYVtestTESTtestTESTtestTESTtest',
+ },
+ debugData,
+ );
+ expect(authObject.tokenType).toBe('api_key');
+ expect(authObject.id).toBe('ak_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.userId).toBeNull();
+ expect(authObject.orgId).toBe('org_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 
@@ -308,8 +329,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('oauth_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('oauth_token');
+ expect(authObject.id).toBe('oat_2VTWUzvGC5UhdJCNx6xG1D98edc');
  expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
+ expect(authObject.userId).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.clientId).toBe('client_2VTWUzvGC5UhdJCNx6xG1D98edc');
  });
  });
 
@@ -332,10 +356,11 @@ describe('authenticatedMachineObject', () => {
  it('properly initializes properties', () => {
  const authObject = authenticatedMachineObject('machine_token', token, verificationResult, debugData);
  expect(authObject.tokenType).toBe('machine_token');
- expect(authObject.name).toBe('my-machine-token');
- expect(authObject.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(authObject.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(authObject.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(authObject.scopes).toEqual(['read:foo', 'write:bar']);
  expect(authObject.claims).toEqual({ foo: 'bar' });
+ expect(authObject.machineId).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  });
  });
 });

packages/backend/src/tokens/__tests__/getAuth.test-d.ts

@@ -1,4 +1,4 @@
-import { assertType, expectTypeOf, test } from 'vitest';
+import { expectTypeOf, test } from 'vitest';
 
 import type { AuthObject } from '../authObjects';
 import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
@@ -32,76 +32,18 @@ test('infers the correct AuthObject type for each accepted token type', () => {
  expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
 });
 
-test('verifies correct properties exist for each token type', () => {
- const request = new Request('https://example.com');
-
- // Session token should have userId
- const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
- expectTypeOf(sessionAuth.userId).toMatchTypeOf<string | null>();
-
- // All machine tokens should have id and subject
- const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
- const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
- const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
-
- expectTypeOf(apiKeyAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.id).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.subject).toMatchTypeOf<string | null>();
- expectTypeOf(oauthTokenAuth.subject).toMatchTypeOf<string | null>();
-
- // Only api_key and machine_token should have name and claims
- expectTypeOf(apiKeyAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(apiKeyAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- expectTypeOf(machineTokenAuth.name).toMatchTypeOf<string | null>();
- expectTypeOf(machineTokenAuth.claims).toMatchTypeOf<Record<string, any> | null>();
-
- // oauth_token should NOT have name and claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(oauthTokenAuth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(oauthTokenAuth.claims);
-});
-
 test('verifies discriminated union works correctly with acceptsToken: any', () => {
  const request = new Request('https://example.com');
 
  const auth = getAuth(request, { acceptsToken: 'any' });
 
  if (auth.tokenType === 'session_token') {
- // Should be SessionAuthObject - has userId
- expectTypeOf(auth.userId).toMatchTypeOf<string | null>();
- // Should NOT have machine token properties
- // @ts-expect-error session_token does not have id property
- assertType<string | null>(auth.id);
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
  } else if (auth.tokenType === 'api_key') {
- // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error api_key does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
  } else if (auth.tokenType === 'machine_token') {
- // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- expectTypeOf(auth.name).toMatchTypeOf<string | null>();
- expectTypeOf(auth.claims).toMatchTypeOf<Record<string, any> | null>();
- // Should NOT have session token properties
- // @ts-expect-error machine_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
  } else if (auth.tokenType === 'oauth_token') {
- // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
- expectTypeOf(auth.id).toMatchTypeOf<string | null>();
- // Should NOT have name or claims
- // @ts-expect-error oauth_token does not have name property
- assertType<string | null>(auth.name);
- // @ts-expect-error oauth_token does not have claims property
- assertType<Record<string, any> | null>(auth.claims);
- // Should NOT have session token properties
- // @ts-expect-error oauth_token does not have userId property
- assertType<string | null>(auth.userId);
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
  }
 });

packages/backend/src/tokens/__tests__/verify.test.ts

@@ -119,9 +119,9 @@ describe('tokens.verifyMachineAuthToken(token, options)', () => {
  expect(result.errors).toBeUndefined();
 
  const data = result.data as MachineToken;
- expect(data.id).toBe('mt_ey966f1b1xf93586b2debdcadb0b3bd1');
+ expect(data.id).toBe('m2m_ey966f1b1xf93586b2debdcadb0b3bd1');
  expect(data.name).toBe('my-machine-token');
- expect(data.subject).toBe('user_2vYVtestTESTtestTESTtestTESTtest');
+ expect(data.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
  expect(data.scopes).toEqual(['read:foo', 'write:bar']);
  expect(data.claims).toEqual({ foo: 'bar' });
  });

packages/backend/src/tokens/authObjects.ts

@@ -11,7 +11,7 @@ import type {
  SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
-import type { APIKey, CreateBackendApiOptions, MachineToken } from '../api';
+import type { APIKey, CreateBackendApiOptions, IdPOAuthAccessToken, MachineToken } from '../api';
 import { createBackendApiClient } from '../api';
 import { isTokenTypeAccepted } from '../internal';
 import type { AuthenticateContext } from './authenticateContext';
@@ -84,22 +84,23 @@ export type SignedOutAuthObject = {
  * While all machine token types share common properties (id, name, subject, etc),
  * this type defines the additional properties that are unique to each token type.
  *
- * @example
- * api_key & machine_token: adds `claims` property
- * oauth_token: adds no additional properties (empty object)
- *
  * @template TAuthenticated - Whether the machine object is authenticated or not
  */
 type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
- api_key: {
- name: TAuthenticated extends true ? string : null;
- claims: TAuthenticated extends true ? Claims | null : null;
- };
+ api_key: TAuthenticated extends true
+ ?
+ | { name: string; claims: Claims | null; userId: string; orgId: null }
+ | { name: string; claims: Claims | null; userId: null; orgId: string }
+ : { name: null; claims: null; userId: null; orgId: null };
  machine_token: {
  name: TAuthenticated extends true ? string : null;
  claims: TAuthenticated extends true ? Claims | null : null;
+ machineId: TAuthenticated extends true ? string : null;
+ };
+ oauth_token: {
+ userId: TAuthenticated extends true ? string : null;
+ clientId: TAuthenticated extends true ? string : null;
  };
- oauth_token: object;
 };
 
 /**
@@ -257,6 +258,8 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ userId: result.subject.startsWith('user_') ? result.subject : null,
+ orgId: result.subject.startsWith('org_') ? result.subject : null,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -267,14 +270,18 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
+ machineId: result.subject,
  } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
+ const result = verificationResult as IdPOAuthAccessToken;
  return {
  ...baseObject,
  tokenType,
- scopes: verificationResult.scopes,
- } as AuthenticatedMachineObject<T>;
+ scopes: result.scopes,
+ userId: result.subject,
+ clientId: result.clientId,
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -304,6 +311,9 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ userId: null,
+ orgId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
@@ -312,13 +322,18 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
+ scopes: null,
+ machineId: null,
  } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
  ...baseObject,
  tokenType,
- } as UnauthenticatedMachineObject<T>;
+ scopes: null,
+ userId: null,
+ clientId: null,
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  default:
  throw new Error(`Invalid token type: ${tokenType}`);
@@ -406,7 +421,7 @@ export const getAuthObjectFromJwt = (
  *
  * @example
  * // Accept 'api_key' or 'machine_token'
- * const authObject = { tokenType: 'machine_token', id: 'mt_123' };
+ * const authObject = { tokenType: 'machine_token', id: 'm2m_123' };
  * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: ['api_key', 'machine_token'] });
  * // result will be the original authObject (since tokenType matches one in the array)
  *

packages/backend/src/tokens/verify.ts

@@ -214,12 +214,12 @@ async function verifyMachineToken(
 }
 
 async function verifyOAuthToken(
-secret: string,
+accessToken: string,
  options: VerifyTokenOptions,
 ): Promise<MachineTokenReturnType<IdPOAuthAccessToken, MachineTokenVerificationError>> {
  try {
  const client = createBackendApiClient(options);
- const verifiedToken = await client.idPOAuthAccessToken.verifySecret(secret);
+ const verifiedToken = await client.idPOAuthAccessToken.verifyAccessToken(accessToken);
  return { data: verifiedToken, tokenType: TokenType.OAuthToken, errors: undefined };
  } catch (err: any) {
  return handleClerkAPIError(TokenType.OAuthToken, err, 'OAuth token not found');

packages/express/src/__tests__/getAuth.test.ts

@@ -21,18 +21,19 @@ describe('getAuth', () => {
  });
 
  it('returns the actual auth object when its tokenType matches acceptsToken', () => {
- const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', subject: 'api_key_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', userId: 'user_12345', orgId: null });
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('api_key');
  expect(result.id).toBe('ak_1234');
- expect(result.subject).toBe('api_key_1234');
+ expect(result.userId).toBe('user_12345');
+ expect(result.orgId).toBeNull();
  });
 
  it('returns the actual auth object if its tokenType is included in the acceptsToken array', () => {
- const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'mt_1234' });
+ const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'm2m_1234' });
  const result = getAuth(req, { acceptsToken: ['machine_token', 'api_key'] });
  expect(result.tokenType).toBe('machine_token');
- expect(result.id).toBe('mt_1234');
+ expect(result.id).toBe('m2m_1234');
  expect(result.subject).toBeUndefined();
  });
 
@@ -41,7 +42,7 @@ describe('getAuth', () => {
  const result = getAuth(req, { acceptsToken: 'api_key' });
  expect(result.tokenType).toBe('session_token'); // reflects the actual token found
  // Properties specific to authenticated objects should be null or undefined
- // @ts-expect-error - userId is not a property of the unauthenticated object
  expect(result.userId).toBeNull();
+ expect(result.orgId).toBeNull();
  });
 });