tessl/npm-auth0

SDK for Auth0 API v2 providing comprehensive authentication, user management, and tenant administration capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

User Information API

Name: tessl/npm-auth0
Author: tessl

The User Information API provides access to user profile information using OIDC-compliant access tokens. It implements the standard OpenID Connect UserInfo endpoint for retrieving authenticated user details.

Capabilities

UserInfo Client

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

Usage Examples:

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);

User Information Response

The UserInfo endpoint returns standard OIDC claims about the authenticated user:

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;
}

Response Example:

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"
}

Error Handling

The UserInfo API uses a specialized error class for handling authentication and authorization errors:

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

Error Response Format:

UserInfo errors typically follow this structure:

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

Common Error Scenarios:

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);
  }
}

Error Parsing

The UserInfo client includes built-in error parsing that handles both structured Auth0 error responses and generic HTTP errors:

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'
    );
  }
}

Configuration Options

The UserInfoClient accepts the same base configuration options as other Auth0 clients:

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;
}