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

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
  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.