# User Information API

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

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

**Usage Examples:**

```typescript
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:

```typescript { .api }
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:**

```typescript
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:

```typescript { .api }
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:

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

**Common Error Scenarios:**

```typescript
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:

```typescript { .api }
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:

```typescript { .api }
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;
}
```

## OIDC Compliance

The UserInfo API fully complies with the OpenID Connect Core 1.0 specification:

- **Standard Claims**: Returns all standard OIDC claims when available
- **Custom Claims**: Supports additional custom claims in the response
- **Bearer Token Authentication**: Uses standard Authorization header format
- **Error Format**: Returns errors in standard OAuth 2.0 format
- **Content Type**: Returns `application/json` content type

**Standard OIDC Claims Supported:**

- `sub` (Subject Identifier)
- `name`, `given_name`, `family_name`, `middle_name`
- `nickname`, `preferred_username`
- `profile`, `picture`, `website`
- `email`, `email_verified`
- `gender`, `birthdate`, `zoneinfo`, `locale`
- `phone_number`, `phone_number_verified`
- `address`
- `updated_at`

**Access Token Requirements:**

- Must be a valid Auth0 access token
- Must have appropriate scope (typically `openid profile email`)
- Must be within expiration time
- Must be issued for the correct audience (if API audience is configured)