feat: get user details from token

docs/authentication.md

@@ -151,6 +151,7 @@ useEffect(() => {
 - `sdk.isInOAuthCallback()` - Check if processing OAuth redirect
 - `sdk.completeOAuth()` - Manually complete OAuth (advanced use)
 - `sdk.getToken()` - Get the logged-in user's access token
+- `sdk.getTokenIdentity()` - Get identity claims (email, firstName, lastName, preferredUsername, name) decoded from the current JWT access token
 - `sdk.logout()` - Logout and clear all authentication state (requires re-initialization to authenticate again)
 - `sdk.updateToken()` - Inject a refreshed token into the SDK instance (useful for backend services managing token lifecycle)
 

src/core/auth/types.ts

@@ -31,3 +31,14 @@ export interface OAuthContext {
   tenantName: string;
   scope: string;
 }
+
+/**
+ * Identity claims decoded from the current JWT access token.
+ */
+export interface TokenIdentity {
+  email?: string;
+  firstName?: string;
+  lastName?: string;
+  preferredUsername?: string;
+  name?: string;
+}

src/core/index.ts

@@ -45,7 +45,7 @@
 
 export { UiPath } from './uipath';
 export type { UiPathSDKConfig } from './config/sdk-config';
-export type { TokenInfo } from './auth/types';
+export type { TokenInfo, TokenIdentity } from './auth/types';
 export * from './errors';
 
 // Pagination (common across all services)

src/core/types.ts

@@ -9,7 +9,7 @@
  */
 
 import type { BaseConfig } from './config/sdk-config';
-import type { TokenInfo } from './auth/types';
+import type { TokenInfo, TokenIdentity } from './auth/types';
 
 export interface IUiPath {
   /** Read-only configuration for the SDK instance */
@@ -47,6 +47,13 @@ export interface IUiPath {
    */
   getToken(): string | undefined;
 
+  /**
+   * Retrieves identity claims (email, firstName, lastName, preferredUsername, name)
+   * of the currently authenticated user by decoding the JWT access token.
+   * Does not work with PAT tokens.
+   */
+  getTokenIdentity(): TokenIdentity;
+
   /**
    * Logout from the SDK, clearing all authentication state.
    * After calling this method, the user will need to re-initialize to authenticate again.

src/core/uipath.ts

@@ -1,14 +1,16 @@
 import { UiPathConfig } from './config/config';
 import { ExecutionContext } from './context/execution';
 import { AuthService } from './auth/service';
-import { TokenInfo } from './auth/types';
+import { TokenInfo, TokenIdentity } from './auth/types';
 import { UiPathSDKConfig, PartialUiPathConfig, BaseConfig, hasOAuthConfig, hasSecretConfig } from './config/sdk-config';
 import { validateConfig, normalizeBaseUrl, isCompleteConfig } from './config/config-utils';
 import { telemetryClient, trackEvent } from './telemetry';
 import { SDKInternalsRegistry } from './internals';
 import { loadFromMetaTags } from './config/runtime';
 import type { IUiPath } from './types';
 import { isInActionCenter } from '../utils/platform';
+import { decodeBase64 } from '../utils/encoding/base64';
+import { AuthenticationError, ValidationError } from './errors';
 
 /**
  * UiPath - Core SDK class for authentication and configuration management.
@@ -238,6 +240,65 @@ export class UiPath implements IUiPath {
     return this.#authService?.getToken();
   }
 
+  /**
+   * Retrieves identity claims of the currently authenticated user by decoding
+   * the JWT access token held in memory. Does not make an API call.
+   *
+   * Returns the following camelCase claims when present on the token:
+   * `email`, `firstName`, `lastName`, `preferredUsername`, `name`.
+   *
+   * @returns The {@link TokenIdentity} extracted from the JWT payload.
+   * @throws {@link AuthenticationError} If the user is not authenticated.
+   * @throws {@link ValidationError} If the token is malformed or its payload cannot be decoded.
+   *
+   * @example
+   * ```typescript
+   * const sdk = new UiPath({ ...config });
+   * await sdk.initialize();
+   *
+   * const identity = sdk.getTokenIdentity();
+   * console.log(identity.email, identity.name);
+   * ```
+   */
+  public getTokenIdentity(): TokenIdentity {
+    if (!this.isAuthenticated()) {
+      throw new AuthenticationError({
+        message: 'User is not authenticated. Call initialize() before getTokenIdentity().'
+      });
+    }
+
+    const token = this.getToken();
+    if (!token) {
+      throw new AuthenticationError({
+        message: 'User is not authenticated. Call initialize() before getTokenIdentity().'
+      });
+    }
+
+    const segments = token.split('.');
+    if (segments.length !== 3) {
+      throw new ValidationError({ message: 'Invalid JWT token format.' });
+    }
+
+    let claims: Record<string, unknown>;
+    try {
+      // Convert base64url to base64 and pad to a multiple of 4.
+      let payload = segments[1].replace(/-/g, '+').replace(/_/g, '/');
+      const paddingLength = (4 - (payload.length % 4)) % 4;
+      payload = payload + '='.repeat(paddingLength);
+      claims = JSON.parse(decodeBase64(payload));
+    } catch {
+      throw new ValidationError({ message: 'Failed to decode JWT token payload.' });
+    }
+
+    return {
+      email: claims.email as string | undefined,
+      firstName: claims.first_name as string | undefined,
+      lastName: claims.last_name as string | undefined,
+      preferredUsername: claims.preferred_username as string | undefined,
+      name: claims.name as string | undefined
+    };
+  }
+
   /**
    * Logout from the SDK, clearing all authentication state.
    * After calling this method, the user will need to re-initialize to authenticate again.

tests/unit/core/uipath.test.ts

@@ -3,22 +3,28 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { UiPath } from '../../../src/core/uipath';
 import { UiPathConfig } from '../../../src/core/config/config';
 import { ExecutionContext } from '../../../src/core/context/execution';
+import { AuthenticationError, ValidationError } from '../../../src/core/errors';
 import { getConfig, getContext, getTokenManager, getPrivateSDK } from '../../utils/setup';
 import { TEST_CONSTANTS } from '../../utils/constants/common';
 
 // ===== MOCKING =====
+const mockAuthState = {
+  token: 'mock-access-token' as string | undefined,
+  hasValidToken: true
+};
+
 const mockTokenManager = {
-  getToken: () => 'mock-access-token',
-  hasValidToken: () => true
+  getToken: () => mockAuthState.token,
+  hasValidToken: () => mockAuthState.hasValidToken
 };
 
 const mockLogout = vi.fn();
 
 vi.mock('../../../src/core/auth/service', () => {
   const AuthService: any = vi.fn().mockImplementation(() => ({
     getTokenManager: () => mockTokenManager,
-    hasValidToken: () => true,
-    getToken: () => 'mock-access-token',
+    hasValidToken: () => mockAuthState.hasValidToken,
+    getToken: () => mockAuthState.token,
     authenticateWithSecret: vi.fn(),
     authenticate: vi.fn().mockResolvedValue(true),
     logout: mockLogout
@@ -34,6 +40,13 @@ vi.mock('../../../src/core/auth/service', () => {
 
 vi.mock('../../../src/core/http/api-client');
 
+// ===== TEST HELPERS =====
+const createJwt = (payload: Record<string, unknown>): string => {
+  const header = Buffer.from(JSON.stringify({ alg: 'none', typ: 'JWT' })).toString('base64url');
+  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return `${header}.${body}.signature`;
+};
+
 // ===== TEST SUITE =====
 describe('UiPath Core', () => {
   describe('Constructor', () => {
@@ -352,6 +365,113 @@ describe('UiPath Core', () => {
     });
   });
 
+  describe('getTokenIdentity', () => {
+    beforeEach(() => {
+      mockAuthState.hasValidToken = true;
+      mockAuthState.token = 'mock-access-token';
+    });
+
+    it('should return all 5 mapped identity fields from JWT claims', () => {
+      mockAuthState.token = createJwt({
+        email: 'jane.doe@example.com',
+        first_name: 'Jane',
+        last_name: 'Doe',
+        preferred_username: 'jane.doe',
+        name: 'Jane Doe'
+      });
+
+      const sdk = new UiPath({
+        baseUrl: TEST_CONSTANTS.BASE_URL,
+        orgName: TEST_CONSTANTS.ORGANIZATION_ID,
+        tenantName: TEST_CONSTANTS.TENANT_ID,
+        secret: TEST_CONSTANTS.CLIENT_SECRET
+      });
+
+      const identity = sdk.getTokenIdentity();
+
+      expect(identity).toEqual({
+        email: 'jane.doe@example.com',
+        firstName: 'Jane',
+        lastName: 'Doe',
+        preferredUsername: 'jane.doe',
+        name: 'Jane Doe'
+      });
+    });
+
+    it('should return undefined for missing claims', () => {
+      mockAuthState.token = createJwt({ email: 'only.email@example.com' });
+
+      const sdk = new UiPath({
+        baseUrl: TEST_CONSTANTS.BASE_URL,
+        orgName: TEST_CONSTANTS.ORGANIZATION_ID,
+        tenantName: TEST_CONSTANTS.TENANT_ID,
+        secret: TEST_CONSTANTS.CLIENT_SECRET
+      });
+
+      const identity = sdk.getTokenIdentity();
+
+      expect(identity.email).toBe('only.email@example.com');
+      expect(identity.firstName).toBeUndefined();
+      expect(identity.lastName).toBeUndefined();
+      expect(identity.preferredUsername).toBeUndefined();
+      expect(identity.name).toBeUndefined();
+    });
+
+    it('should throw AuthenticationError when user is not authenticated', () => {
+      mockAuthState.hasValidToken = false;
+
+      const sdk = new UiPath({
+        baseUrl: TEST_CONSTANTS.BASE_URL,
+        orgName: TEST_CONSTANTS.ORGANIZATION_ID,
+        tenantName: TEST_CONSTANTS.TENANT_ID,
+        secret: TEST_CONSTANTS.CLIENT_SECRET
+      });
+
+      expect(() => sdk.getTokenIdentity()).toThrow(AuthenticationError);
+    });
+
+    it('should throw ValidationError when token has fewer than 3 segments', () => {
+      mockAuthState.token = 'not-a-jwt';
+
+      const sdk = new UiPath({
+        baseUrl: TEST_CONSTANTS.BASE_URL,
+        orgName: TEST_CONSTANTS.ORGANIZATION_ID,
+        tenantName: TEST_CONSTANTS.TENANT_ID,
+        secret: TEST_CONSTANTS.CLIENT_SECRET
+      });
+
+      expect(() => sdk.getTokenIdentity()).toThrow(ValidationError);
+    });
+
+    it('should throw ValidationError when token has more than 3 segments', () => {
+      mockAuthState.token = 'header.payload.sig.extra';
+
+      const sdk = new UiPath({
+        baseUrl: TEST_CONSTANTS.BASE_URL,
+        orgName: TEST_CONSTANTS.ORGANIZATION_ID,
+        tenantName: TEST_CONSTANTS.TENANT_ID,
+        secret: TEST_CONSTANTS.CLIENT_SECRET
+      });
+
+      expect(() => sdk.getTokenIdentity()).toThrow(ValidationError);
+    });
+
+    it('should throw ValidationError when payload is not valid JSON', () => {
+      const header = Buffer.from(JSON.stringify({ alg: 'none' })).toString('base64url');
+      const invalidPayload = Buffer.from('not-json-content').toString('base64url');
+      mockAuthState.token = `${header}.${invalidPayload}.signature`;
+
+      const sdk = new UiPath({
+        baseUrl: TEST_CONSTANTS.BASE_URL,
+        orgName: TEST_CONSTANTS.ORGANIZATION_ID,
+        tenantName: TEST_CONSTANTS.TENANT_ID,
+        secret: TEST_CONSTANTS.CLIENT_SECRET
+      });
+
+      expect(() => sdk.getTokenIdentity()).toThrow(ValidationError);
+    });
+  });
+
   describe('Multiple Instance Support', () => {
     it('should support creating multiple independent instances', () => {
       const sdk1 = new UiPath({