# Impersonation Reference

### Create Impersonation Session

Creates a new user impersonation session.

#### Arguments

- **employeeEmail** string required  
  The email of the employee who is performing the impersonation
- **targetUserId** string required  
  The ID of the user to be impersonated
- **userAgent** string required  
  The user agent of the employee performing the impersonation
- **ipAddress** string required  
  The IP address of the employee performing the impersonation
- **metadata** Json Value  
  Any additional metadata to attach to the impersonation session

#### Successful Response

- **sessionId** string  
  The unique identifier for the impersonation session
- **impersonationSessionToken** string  
  The token to use for authenticating as the impersonated user
- **expiresAt** number  
  Unix timestamp when the impersonation session expires

#### Error Types

- **ImpersonationDisabled**
  Impersonation is disabled for this organization
- **UnauthorizedEmployee**  
  The provided employee is not authorized to perform impersonation
- **UnexpectedError**  
  An unexpected error occurred during the operation

#### Example Code Snippets

```javascript
const auth = createClient({ url, integrationKey });

const result = await auth.impersonation.create({

employeeEmail: "example@acmeinc.com",

targetUserId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",

userAgent: "Mozilla/5.0 (Macintosh...",

ipAddress: "136.38.37.199",

metadata: {

"example": "value"

}
});

if (result.ok) {

console.log("Impersonation session created successfully");
  console.log("Session ID:", result.data.sessionId);
  console.log("Token:", result.data.impersonationSessionToken);
} else {
  console.log(`Error: ${result.error}`);
}
```

### Validate Impersonation Session

Validates an impersonation session.

#### Arguments

- **impersonationToken** string required  
  The impersonation session token to validate
- **userAgent** string required  
  The user agent of the employee performing the impersonation
- **ipAddress** string required  
  The IP address of the employee performing the impersonation

#### Successful Response

- **impersonationSessionId** string  
  The unique identifier for the impersonation session
- **employeeEmail** string  
  The email of the employee who is performing the impersonation
- **targetUserId** string  
  The ID of the user being impersonated
- **createdAt** number  
  Unix timestamp when the session was created
- **expiresAt** number  
  Unix timestamp when the session expires
- **metadata** Json Value | null  
  Additional metadata attached to the impersonation session

#### Error Types

- **ImpersonationNotEnabled**
  Impersonation is not enabled for this organization
- **InvalidImpersonationToken**
  The impersonation token is invalid or expired
- **SessionNotFound**
  The impersonation session could not be found
- **IpAddressMismatch**
  The provided IP address does not match the one on record
- **UserAgentMismatch**
  The provided user agent does not match the one on record
- **UnexpectedError**
  An unexpected error occurred during the operation

### Fetch Impersonation Session by ID

Fetches an impersonation session by session ID.

#### Arguments

- **impersonationSessionId** string required  
  The impersonation session ID to fetch

#### Successful Response

- **impersonationSessionId** string  
  The unique identifier for the impersonation session
- **employeeEmail** string  
  The email of the employee who is performing the impersonation
- **targetUserId** string  
  The ID of the user being impersonated
- **metadata** Json Value  
  Additional metadata attached to the impersonation session
- **createdAt** number  
  Unix timestamp when the session was created
- **expiresAt** number  
  Unix timestamp when the session expires

#### Error Types

- **SessionNotFound**
  The impersonation session could not be found
- **UnexpectedError**
  An unexpected error occurred during the operation

### Fetch All Impersonation Sessions for Employee

Fetches all active impersonation sessions for an employee.

#### Arguments

- **employeeEmail** string required  
  The email of the employee whose impersonation sessions are to be fetched

#### Successful Response

- **sessions** Array<ImpersonationSessionInfo>  
  List of active impersonation sessions for the employee

#### Error Types

- **UnexpectedError**
  An unexpected error occurred during the operation

### Invalidate Impersonation Session by ID

Invalidates (deletes) an impersonation session by session ID.

#### Arguments

- **impersonationSessionId** string required  
  The impersonation session ID to invalidate

#### Successful Response

Returns an empty response on success

#### Error Types

- **SessionNotFound**
  The impersonation session could not be found
- **UnexpectedError**
  An unexpected error occurred during the operation

### Configuring Impersonation Settings

You can configure the impersonation settings, such as session duration and who can impersonate, in the 'user_impersonation.jsonc' file.

#### Arguments

- **enabled** boolean  
  Enable or disable user impersonation feature globally. Defaults to false.
- **impersonation_duration_secs** number  
  Duration for which an impersonation session remains valid (in seconds). Defaults to 3600 (1 hour).
- **disallow_ip_address_changes** boolean  
  Whether to restrict impersonation sessions to the IP address of the original user. Defaults to true.
- **who_can_impersonate** object  
  This section defines who is allowed to impersonate other users. Default is that no one can impersonate anyone.