User Information API

class UserInfoClient extends BaseAPI {
  constructor(options: { domain: string } & ClientOptions);
  
  getUserInfo(
    accessToken: string,
    initOverrides?: InitOverride
  ): Promise<JSONApiResponse<UserInfoResponse>>;
}

import { UserInfoClient } from "auth0";

// Initialize the client
const userInfoClient = new UserInfoClient({
  domain: "your-domain.auth0.com"
});

// Get user information using an access token
const userInfo = await userInfoClient.getUserInfo(accessToken);

console.log("User ID:", userInfo.data.sub);
console.log("Email:", userInfo.data.email);
console.log("Name:", userInfo.data.name);

interface UserInfoResponse {
  /** Subject identifier - unique identifier for the user */
  sub: string;
  
  /** Full name of the user */
  name: string;
  
  /** Given name(s) or first name(s) of the user */
  given_name?: string;
  
  /** Surname(s) or last name(s) of the user */
  family_name?: string;
  
  /** Middle name(s) of the user */
  middle_name?: string;
  
  /** Casual name of the user */
  nickname: string;
  
  /** Shorthand name by which the user wishes to be referred to */
  preferred_username?: string;
  
  /** URL of the user's profile picture */
  profile?: string;
  
  /** URL of the user's profile picture */
  picture?: string;
  
  /** URL of the user's web page or blog */
  website?: string;
  
  /** User's preferred e-mail address */
  email: string;
  
  /** True if the user's e-mail address has been verified; otherwise false */
  email_verified: boolean;
  
  /** User's gender */
  gender?: string;
  
  /** User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format */
  birthdate?: string;
  
  /** String from zoneinfo time zone database representing the user's time zone */
  zoneinfo?: string;
  
  /** User's locale, represented as a BCP47 [RFC5646] language tag */
  locale?: string;
  
  /** User's preferred telephone number */
  phone_number?: string;
  
  /** True if the user's phone number has been verified; otherwise false */
  phone_number_verified?: string;
  
  /** User's preferred postal address */
  address?: {
    /** Country name component */
    country?: string;
  };
  
  /** Time the user's information was last updated */
  updated_at: string;
  
  /** Additional custom claims that may be present */
  [key: string]: unknown;
}

const userInfo = await userInfoClient.getUserInfo("access_token_here");

// userInfo.data contains:
{
  "sub": "auth0|507f1f77bcf86cd799439011",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "nickname": "johnny",
  "email": "john.doe@example.com",
  "email_verified": true,
  "picture": "https://s.gravatar.com/avatar/123456789.png",
  "updated_at": "2023-10-01T12:00:00.000Z",
  "locale": "en-US",
  "custom_claim": "custom_value"
}

class UserInfoError extends Error {
  override name: 'UserInfoError';
  
  constructor(
    public error: string,
    public error_description: string,
    public statusCode: number,
    public body: string,
    public headers: Headers
  );
}

interface UserInfoErrorResponse {
  error_description: string;
  error: string;
}

try {
  const userInfo = await userInfoClient.getUserInfo(accessToken);
} catch (error) {
  if (error instanceof UserInfoError) {
    console.error("UserInfo Error:", error.error);
    console.error("Description:", error.error_description);
    console.error("Status Code:", error.statusCode);
    
    // Common error types:
    // - "invalid_token": Access token is invalid or expired
    // - "insufficient_scope": Token lacks required scope
    // - "unauthorized": Token is not authorized for this endpoint
  } else if (error instanceof ResponseError) {
    console.error("HTTP Error:", error.statusCode);
  }
}

async function parseError(response: Response): Promise<UserInfoError | ResponseError> {
  const body = await response.text();
  let data: UserInfoErrorResponse;

  try {
    data = JSON.parse(body) as UserInfoErrorResponse;
    return new UserInfoError(
      data.error,
      data.error_description,
      response.status,
      body,
      response.headers
    );
  } catch (_) {
    return new ResponseError(
      response.status,
      body,
      response.headers,
      'Response returned an error code'
    );
  }
}

interface UserInfoClientOptions extends ClientOptions {
  /** Auth0 domain (e.g., "your-domain.auth0.com") */
  domain: string;
}

interface ClientOptions {
  /** Enable/disable telemetry (default: true) */
  telemetry?: boolean;
  
  /** Custom client information for telemetry */
  clientInfo?: { name: string; [key: string]: unknown };
  
  /** Custom fetch implementation */
  fetch?: FetchAPI;
  
  /** Request middleware */
  middleware?: Middleware[];
  
  /** HTTP agent for proxy support */
  agent?: Dispatcher;
  
  /** Default headers for all requests */
  headers?: HTTPHeaders;
  
  /** Request timeout in milliseconds */
  timeoutDuration?: number;
  
  /** Retry configuration */
  retry?: RetryConfiguration;
}