@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+'@clerk/nextjs': minor
+'@clerk/shared': minor
+---
+
+OAuth access-token auth objects now support `has({ oauth_scope: 'scope' })` to authorize against the exact scopes granted in the token.
@@ -103,13 +103,17 @@ app.get('/m2m', c => {
         .addFile('src/server/app.ts', () =>
           createAppFile(`
 app.get('/oauth-verify', c => {
-  const { userId, tokenType } = getAuth(c, { acceptsToken: 'oauth_token' });
+  const auth = getAuth(c, { acceptsToken: 'oauth_token' });
 
-  if (!userId) {
+  if (!auth.userId) {
     return c.text('Unauthorized', 401);
   }
 
-  return c.json({ userId, tokenType });
+  if (!auth.has({ oauth_scope: 'profile' })) {
+    return c.text('Forbidden', 403);
+  }
+
+  return c.json({ userId: auth.userId, tokenType: auth.tokenType });
 });
 
 app.get('/oauth/callback', c => {
 
@@ -358,8 +358,14 @@ describe('authenticatedMachineObject', () => {
       expect(retrievedToken).toBe(token);
     });
 
-    it('has() always returns false', () => {
+    it('has() checks exact OAuth scopes and denies other authorization checks', () => {
       const authObject = authenticatedMachineObject('oauth_token', token, verificationResult, debugData);
+      expect(authObject.has({ oauth_scope: 'read:foo' })).toBe(true);
+      expect(authObject.has({ oauth_scope: 'write:bar' })).toBe(true);
+      expect(authObject.has({ oauth_scope: 'read:baz' })).toBe(false);
+      expect(authObject.has({ oauth_scope: 'READ:FOO' })).toBe(false);
+      expect(authObject.has({ oauth_scope: '' })).toBe(false);
+      expect(authObject.has({ role: 'org:admin' })).toBe(false);
       expect(authObject.has({})).toBe(false);
     });
 
@@ -415,6 +421,18 @@ describe('unauthenticatedMachineObject', () => {
     expect(authObject.has({})).toBe(false);
   });
 
+  it('accepts OAuth scope checks and returns false for unauthenticated OAuth tokens', () => {
+    const authObject = unauthenticatedMachineObject('oauth_token');
+    expect(authObject.has({ oauth_scope: 'read:foo' })).toBe(false);
+  });
+
+  it('does not expose OAuth scope checks on other machine token types', () => {
+    const authObject = unauthenticatedMachineObject('api_key');
+
+    // @ts-expect-error OAuth scope checks are only available for OAuth tokens.
+    expect(authObject.has({ oauth_scope: 'read:foo' })).toBe(false);
+  });
+
   it('getToken always returns null ', async () => {
     const authObject = unauthenticatedMachineObject('m2m_token');
     const retrievedToken = await authObject.getToken();
 
@@ -42,10 +42,14 @@ describe('getAuth() or auth() with request parameter', () => {
       expectTypeOf(auth).toExtend<SessionAuthObject>();
     } else if (auth.tokenType === 'api_key') {
       expectTypeOf(auth).toExtend<MachineAuthObject<'api_key'>>();
+      // @ts-expect-error OAuth scope checks are only available for OAuth tokens.
+      auth.has({ oauth_scope: 'profile' });
     } else if (auth.tokenType === 'm2m_token') {
       expectTypeOf(auth).toExtend<MachineAuthObject<'m2m_token'>>();
     } else if (auth.tokenType === 'oauth_token') {
       expectTypeOf(auth).toExtend<MachineAuthObject<'oauth_token'>>();
+      auth.has({ oauth_scope: 'profile' });
+      auth.has({ role: 'org:admin' });
     }
   });
 });
 
@@ -1,6 +1,7 @@
-import { createCheckAuthorization } from '@clerk/shared/authorization';
+import { createCheckAuthorization, createCheckAuthorizationFromOAuthScopes } from '@clerk/shared/authorization';
 import { __experimental_JWTPayloadToAuthObjectProperties } from '@clerk/shared/jwtPayloadParser';
 import type {
+  CheckAuthorizationFromOAuthScopes,
   CheckAuthorizationFromSessionClaims,
   Jwt,
   JwtPayload,
@@ -31,6 +32,10 @@ type AuthObjectDebug = () => AuthObjectDebugData;
 
 type Claims = Record<string, any>;
 
+type CheckAuthorizationFromMachineToken<T extends MachineTokenType> = T extends typeof TokenType.OAuthToken
+  ? CheckAuthorizationFromOAuthScopes
+  : CheckAuthorizationFromSessionClaims;
+
 /**
  * @internal
  */
@@ -119,7 +124,7 @@ export type AuthenticatedMachineObject<T extends MachineTokenType = MachineToken
       subject: string;
       scopes: string[];
       getToken: () => Promise<string>;
-      has: CheckAuthorizationFromSessionClaims;
+      has: CheckAuthorizationFromMachineToken<T>;
       debug: AuthObjectDebug;
       tokenType: T;
       isAuthenticated: true;
@@ -140,7 +145,7 @@ export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTok
       subject: null;
       scopes: null;
       getToken: () => Promise<null>;
-      has: CheckAuthorizationFromSessionClaims;
+      has: CheckAuthorizationFromMachineToken<T>;
       debug: AuthObjectDebug;
       tokenType: T;
       isAuthenticated: false;
@@ -310,6 +315,10 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
         scopes: result.scopes,
         userId: result.subject,
         clientId: result.clientId,
+        has: createCheckAuthorizationFromOAuthScopes({
+          userId: result.subject,
+          oauthScopes: result.scopes,
+        }),
       } as unknown as AuthenticatedMachineObject<T>;
     }
     default:
 
@@ -166,6 +166,86 @@ describe('getAuthDataFromRequest', () => {
     expect(auth.isAuthenticated).toBe(true);
   });
 
+  it('reconstructs OAuth scope authorization from encrypted machine auth data', () => {
+    const machineAuthObject = createMockMachineAuthObject({
+      tokenType: 'oauth_token',
+      id: 'oat_id123',
+      subject: 'user_12345',
+      userId: 'user_12345',
+      clientId: 'client_12345',
+      scopes: ['profile', 'email'],
+      isAuthenticated: true,
+    });
+
+    const req = mockRequest({
+      url: '/api/protected',
+      headers: new Headers({
+        [constants.Headers.Authorization]: 'Bearer oat_secret123',
+      }),
+      machineAuthObject,
+    });
+
+    const auth = getAuthDataFromRequest(req, { acceptsToken: 'oauth_token' });
+
+    expect(auth.tokenType).toBe('oauth_token');
+    expect(auth.isAuthenticated).toBe(true);
+    if (auth.tokenType !== 'oauth_token') {
+      throw new Error('Expected an OAuth auth object');
+    }
+    expect(auth.has({ oauth_scope: 'profile' })).toBe(true);
+    expect(auth.has({ oauth_scope: 'email' })).toBe(true);
+    expect(auth.has({ oauth_scope: 'openid' })).toBe(false);
+    expect(auth.has({ oauth_scope: 'PROFILE' })).toBe(false);
+  });
+
+  it('keeps OAuth scope authorization disabled for unauthenticated reconstructed auth data', () => {
+    const machineAuthObject = createMockMachineAuthObject({
+      tokenType: 'oauth_token',
+      isAuthenticated: false,
+    });
+
+    const req = mockRequest({
+      url: '/api/protected',
+      headers: new Headers({
+        [constants.Headers.Authorization]: 'Bearer oat_invalid',
+      }),
+      machineAuthObject,
+    });
+
+    const auth = getAuthDataFromRequest(req, { acceptsToken: 'oauth_token' });
+
+    expect(auth.tokenType).toBe('oauth_token');
+    expect(auth.isAuthenticated).toBe(false);
+    if (auth.tokenType !== 'oauth_token') {
+      throw new Error('Expected an OAuth auth object');
+    }
+    expect(auth.has({ oauth_scope: 'profile' })).toBe(false);
+  });
+
+  it('keeps non-OAuth machine token authorization disabled after reconstruction', () => {
+    const machineAuthObject = createMockMachineAuthObject({
+      tokenType: 'api_key',
+      id: 'ak_id123',
+      subject: 'user_12345',
+      scopes: ['profile'],
+      isAuthenticated: true,
+    });
+
+    const req = mockRequest({
+      url: '/api/protected',
+      headers: new Headers({
+        [constants.Headers.Authorization]: 'Bearer ak_secret123',
+      }),
+      machineAuthObject,
+    });
+
+    const auth = getAuthDataFromRequest(req, { acceptsToken: 'api_key' });
+
+    expect(auth.tokenType).toBe('api_key');
+    expect(auth.isAuthenticated).toBe(true);
+    expect(auth.has({})).toBe(false);
+  });
+
   it('returns authenticated object when token type exists in acceptsToken array', () => {
     const machineAuthObject = createMockMachineAuthObject({
       tokenType: 'api_key',
 
@@ -17,6 +17,7 @@ import {
   TokenType,
 } from '@clerk/backend/internal';
 import { decodeJwt } from '@clerk/backend/jwt';
+import { createCheckAuthorizationFromOAuthScopes } from '@clerk/shared/authorization';
 import type { PendingSessionOptions } from '@clerk/shared/types';
 
 import type { LoggerNoCommit } from '../../utils/debugLogger';
@@ -171,7 +172,13 @@ const handleMachineToken = (
     return {
       ...authObject,
       getToken: () => (authObject.isAuthenticated ? Promise.resolve(bearerToken) : Promise.resolve(null)),
-      has: () => false,
+      has:
+        authObject.tokenType === TokenType.OAuthToken
+          ? createCheckAuthorizationFromOAuthScopes({
+              userId: authObject.userId,
+              oauthScopes: authObject.scopes,
+            })
+          : () => false,
     } as MachineAuthObject<MachineTokenType>;
   }
 
 
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { createCheckAuthorization, splitByScope } from '../authorization';
+import { createCheckAuthorization, createCheckAuthorizationFromOAuthScopes, splitByScope } from '../authorization';
 
 describe('createCheckAuthorization', () => {
   it('correctly parses features', () => {
@@ -377,6 +377,91 @@ describe('createCheckAuthorization', () => {
   });
 });
 
+describe('createCheckAuthorizationFromOAuthScopes', () => {
+  it('authorizes an exact, case-sensitive scope match', () => {
+    const has = createCheckAuthorizationFromOAuthScopes({
+      userId: 'user_123',
+      oauthScopes: ['profile', 'Email'],
+    });
+
+    expect(has({ oauth_scope: 'profile' })).toBe(true);
+    expect(has({ oauth_scope: 'Email' })).toBe(true);
+    expect(has({ oauth_scope: 'PROFILE' })).toBe(false);
+    expect(has({ oauth_scope: 'email' })).toBe(false);
+    expect(has({ oauth_scope: 'missing' })).toBe(false);
+  });
+
+  it('fails closed for invalid requested scopes', () => {
+    const has = createCheckAuthorizationFromOAuthScopes({
+      userId: 'user_123',
+      oauthScopes: ['profile'],
+    });
+
+    expect(has({ oauth_scope: '' })).toBe(false);
+    expect(has({ oauth_scope: null } as any)).toBe(false);
+    expect(has({ oauth_scope: 123 } as any)).toBe(false);
+    expect(has({ oauth_scope: undefined } as any)).toBe(false);
+  });
+
+  it.each([undefined, null, {}, ['profile', 123], ['profile', '']])(
+    'fails closed for malformed granted scopes: %j',
+    oauthScopes => {
+      const has = createCheckAuthorizationFromOAuthScopes({
+        userId: 'user_123',
+        oauthScopes: oauthScopes as any,
+      });
+
+      expect(has({ oauth_scope: 'profile' })).toBe(false);
+    },
+  );
+
+  it.each([undefined, null, ''])('fails when userId is missing: %j', userId => {
+    const has = createCheckAuthorizationFromOAuthScopes({
+      userId,
+      oauthScopes: ['profile'],
+    });
+
+    expect(has({ oauth_scope: 'profile' })).toBe(false);
+  });
+
+  it('accepts previous session authorization shapes but denies them', () => {
+    const has = createCheckAuthorizationFromOAuthScopes({
+      userId: 'user_123',
+      oauthScopes: ['profile'],
+    });
+
+    expect(has({ role: 'org:admin' })).toBe(false);
+    expect(has({ permission: 'org:read' })).toBe(false);
+    expect(has({ feature: 'user:premium' })).toBe(false);
+    expect(has({ plan: 'user:pro' })).toBe(false);
+    expect(has({ reverification: 'strict' })).toBe(false);
+  });
+
+  it.each([
+    { role: 'org:admin' },
+    { permission: 'org:read' },
+    { feature: 'user:premium' },
+    { plan: 'user:pro' },
+    { reverification: 'strict' },
+  ])('denies a valid OAuth scope mixed with another recognized dimension: %j', params => {
+    const has = createCheckAuthorizationFromOAuthScopes({
+      userId: 'user_123',
+      oauthScopes: ['profile'],
+    });
+
+    expect(has({ oauth_scope: 'profile', ...params } as any)).toBe(false);
+  });
+
+  it('fails when no authorization dimension is requested', () => {
+    const has = createCheckAuthorizationFromOAuthScopes({
+      userId: 'user_123',
+      oauthScopes: ['profile'],
+    });
+
+    expect(has({})).toBe(false);
+  });
+});
+
 describe('splitByScope', () => {
   it('correctly splits features by scope', () => {
     const { org, user } = splitByScope('o:reservations,u:dashboard');