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 JsonValue

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

Node Python Go Java C#

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}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.create(
    employee_email="example@acmeinc.com",
    target_user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    user_agent="Mozilla/5.0 (Macintosh...",
    ip_address="136.38.37.199",
    metadata={
        "example": "value"
    }
)

if is_ok(result):
    print("Impersonation session created successfully")
    print(f"Session ID: {result.data.session_id}")
    print(f"Token: {result.data.impersonation_session_token}")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Impersonation.Create(ctx, byo.CreateImpersonationSessionCommand{
    EmployeeEmail: "example@acmeinc.com",
    TargetUserID:  "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    UserAgent:     "Mozilla/5.0 (Macintosh...",
    IPAddress:     "136.38.37.199",
    Metadata: map[string]any{
        "example": "value",
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.ImpersonationSessionToken)

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

CreateImpersonationSessionCommand command = CreateImpersonationSessionCommand.builder()
    .employeeEmail("example@acmeinc.com")
    .targetUserId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .userAgent("Mozilla/5.0 (Macintosh...")
    .ipAddress("136.38.37.199")
    .metadata(JsonValue.of(Map.of("example", "value")))
    .build();

try {
    CreateImpersonationSessionResponse response = client.impersonation.create(command);
    System.out.println("Impersonation session created successfully");
    System.out.println("Session ID: " + response.getSessionId());
    System.out.println("Token: " + response.getImpersonationSessionToken());
} catch (CreateImpersonationSessionException.UnauthorizedEmployee e) {
    System.out.println("Unauthorized employee: " + e.getDetails());
} catch (CreateImpersonationSessionException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions
{
    Url = url,
    IntegrationKey = integrationKey
});

var command = new CreateImpersonationSessionCommand
{
    EmployeeEmail = "example@acmeinc.com",
    TargetUserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    UserAgent = "Mozilla/5.0 (Macintosh...",
    IpAddress = "136.38.37.199",
    Metadata = JsonSerializer.SerializeToElement(new { example = "value" })
};

try
{
    var response = await client.Impersonation.CreateAsync(command);
    Console.WriteLine("Impersonation session created successfully");
    Console.WriteLine($"Session ID: {response.SessionId}");
    Console.WriteLine($"Token: {response.ImpersonationSessionToken}");
}
catch (CreateImpersonationSessionException.UnauthorizedEmployee ex)
{
    Console.WriteLine($"Unauthorized employee: {ex.Details}");
}
catch (CreateImpersonationSessionException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    sessionId: "l5NeYIUscTuVZz7GriwydE",
    impersonationSessionToken: "impersonate_l5NeYI...",
    expiresAt: 1756846846
  }
}

Result(
    data=CreateImpersonationSessionResponse(
        session_id="l5NeYIUscTuVZz7GriwydE",
        impersonation_session_token="impersonate_l5NeYI...",
        expires_at=1756846846
    )
)

byo.CreateImpersonationSessionResponse{
    SessionID:                 "l5NeYIUscTuVZz7GriwydE",
    ImpersonationSessionToken: "impersonate_l5NeYI...",
    ExpiresAt:                 1756846846,
}

CreateImpersonationSessionResponse(
    sessionId="l5NeYIUscTuVZz7GriwydE",
    impersonationSessionToken="impersonate_l5NeYI...",
    expiresAt=1756846846
)

CreateImpersonationSessionResponse
{
    SessionId = "l5NeYIUscTuVZz7GriwydE",
    ImpersonationSessionToken = "impersonate_l5NeYI...",
    ExpiresAt = 1756846846
}

---

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

Node Python Go Java C#

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

const result = await auth.impersonation.validate({
  impersonationToken: "impersonate_L8piQvaIeYo...",
  userAgent: "Mozilla/5.0 (Macintosh...",
  ipAddress: "136.38.37.199",
});

if (result.ok) {
  console.log("Impersonation validated successfully");
  console.log("Session ID:", result.data.impersonationSessionId);
  console.log("Employee:", result.data.employeeEmail);
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.validate(
    impersonation_token="impersonate_L8piQvaIeYo...",
    user_agent="Mozilla/5.0 (Macintosh...",
    ip_address="136.38.37.199"
)

if is_ok(result):
    print("Impersonation validated successfully")
    print(f"Session ID: {result.data.impersonation_session_id}")
    print(f"Employee: {result.data.employee_email}")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Impersonation.Validate(ctx, byo.ValidateImpersonationSessionCommand{
    ImpersonationToken: "impersonate_L8piQvaIeYo...",
    UserAgent:          "Mozilla/5.0 (Macintosh...",
    IPAddress:          "136.38.37.199",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.EmployeeEmail)

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

ValidateImpersonationSessionCommand command = ValidateImpersonationSessionCommand.builder()
    .impersonationToken("impersonate_L8piQvaIeYo...")
    .userAgent("Mozilla/5.0 (Macintosh...")
    .ipAddress("136.38.37.199")
    .build();

try {
    ValidateImpersonationSessionResponse response = client.impersonation.validate(command);
    System.out.println("Impersonation validated successfully");
    System.out.println("Session ID: " + response.getImpersonationSessionId());
    System.out.println("Employee: " + response.getEmployeeEmail());
} catch (ValidateImpersonationSessionException.InvalidImpersonationToken e) {
    System.out.println("Invalid token: " + e.getDetails());
} catch (ValidateImpersonationSessionException.IpAddressMismatch e) {
    System.out.println("IP address mismatch");
} catch (ValidateImpersonationSessionException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new ValidateImpersonationSessionCommand
{
    ImpersonationToken = "impersonate_L8piQvaIeYo...",
    UserAgent = "Mozilla/5.0 (Macintosh...",
    IpAddress = "136.38.37.199"
};

try
{
    var response = await client.Impersonation.ValidateAsync(command);
    Console.WriteLine("Impersonation validated successfully");
    Console.WriteLine($"Session ID: {response.ImpersonationSessionId}");
    Console.WriteLine($"Employee: {response.EmployeeEmail}");
}
catch (ValidateImpersonationSessionException.InvalidImpersonationToken ex)
{
    Console.WriteLine($"Invalid token: {ex.Details}");
}
catch (ValidateImpersonationSessionException.IpAddressMismatch ex)
{
    Console.WriteLine("IP address mismatch");
}

Response

{
  ok: true,
  data: {
    impersonationSessionId: "L8piQvaIeYoAI6Hl3Rct7F",
    employeeEmail: "example@acmeinc.com",
    targetUserId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    createdAt: 1756844019,
    expiresAt: 1756847619,
    metadata: {
      "example": "value"
    }
  }
}

Result(
    data=ValidateImpersonationSessionResponse(
        impersonation_session_id="L8piQvaIeYoAI6Hl3Rct7F",
        employee_email="example@acmeinc.com",
        target_user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
        created_at=1756844019,
        expires_at=1756847619,
        metadata={
            "example": "value"
        }
    )
)

byo.ValidateImpersonationSessionResponse{
    ImpersonationSessionID: "L8piQvaIeYoAI6Hl3Rct7F",
    EmployeeEmail:          "example@acmeinc.com",
    TargetUserID:           "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    CreatedAt:              1756844019,
    ExpiresAt:              1756847619,
}

ValidateImpersonationSessionResponse(
    impersonationSessionId="L8piQvaIeYoAI6Hl3Rct7F",
    employeeEmail="example@acmeinc.com",
    targetUserId="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    createdAt=1756844019,
    expiresAt=1756847619,
    metadata={example=value}
)

ValidateImpersonationSessionResponse
{
    ImpersonationSessionId = "L8piQvaIeYoAI6Hl3Rct7F",
    EmployeeEmail = "example@acmeinc.com",
    TargetUserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    CreatedAt = 1756844019,
    ExpiresAt = 1756847619,
    Metadata = new { example = "value" }
}

---

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 JsonValue

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

Node Python Go Java C#

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

const result = await auth.impersonation.fetchById({
  impersonationSessionId: "L8piQvaIeYo...",
});

if (result.ok) {
  console.log("Impersonation session fetched successfully");
  console.log("Session ID:", result.data.impersonationSessionId);
  console.log("Target User:", result.data.targetUserId);
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.fetch_by_id(
    impersonation_session_id="L8piQvaIeYo..."
)

if is_ok(result):
    print("Impersonation session fetched successfully")
    print(f"Session ID: {result.data.impersonation_session_id}")
    print(f"Target User: {result.data.target_user_id}")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Impersonation.FetchByID(ctx, byo.FetchImpersonationSessionByIdCommand{
    ImpersonationSessionID: "L8piQvaIeYo...",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.TargetUserID)

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

FetchImpersonationSessionByIdCommand command = FetchImpersonationSessionByIdCommand.builder()
    .impersonationSessionId("L8piQvaIeYo...")
    .build();

try {
    ImpersonationSessionInfo response = client.impersonation.fetchById(command);
    System.out.println("Impersonation session fetched successfully");
    System.out.println("Session ID: " + response.getImpersonationSessionId());
    System.out.println("Target User: " + response.getTargetUserId());
} catch (FetchImpersonationSessionByIdException.SessionNotFound e) {
    System.out.println("Session not found");
} catch (FetchImpersonationSessionByIdException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new FetchImpersonationSessionByIdCommand
{
    ImpersonationSessionId = "L8piQvaIeYo..."
};

try
{
    var response = await client.Impersonation.FetchByIdAsync(command);
    Console.WriteLine("Impersonation session fetched successfully");
    Console.WriteLine($"Session ID: {response.ImpersonationSessionId}");
    Console.WriteLine($"Target User: {response.TargetUserId}");
}
catch (FetchImpersonationSessionByIdException.SessionNotFound)
{
    Console.WriteLine("Session not found");
}
catch (FetchImpersonationSessionByIdException e)
{
    Console.WriteLine($"Error: {e.Message}");
}

Response

{
  ok: true,
  data: {
    impersonationSessionId: "L8piQvaIeYoAI6Hl3Rct7F",
    employeeEmail: "example@acmeinc.com",
    targetUserId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    metadata: {
      "example": "value"
    },
    createdAt: 1756844019,
    expiresAt: 1756847619
  }
}

Result(
    data=ImpersonationSessionInfo(
        impersonation_session_id="L8piQvaIeYoAI6Hl3Rct7F",
        employee_email="example@acmeinc.com",
        target_user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
        metadata={
            "example": "value"
        },
        created_at=1756844019,
        expires_at=1756847619
    )
)

byo.ImpersonationSessionInfo{
    ImpersonationSessionID: "L8piQvaIeYoAI6Hl3Rct7F",
    EmployeeEmail:          "example@acmeinc.com",
    TargetUserID:           "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    CreatedAt:              1756844019,
    ExpiresAt:              1756847619,
}

ImpersonationSessionInfo(
    impersonationSessionId="L8piQvaIeYoAI6Hl3Rct7F",
    employeeEmail="example@acmeinc.com",
    targetUserId="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    metadata={example=value},
    createdAt=1756844019,
    expiresAt=1756847619
)

ImpersonationSessionInfo
{
    ImpersonationSessionId = "L8piQvaIeYoAI6Hl3Rct7F",
    EmployeeEmail = "example@acmeinc.com",
    TargetUserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    Metadata = new Dictionary<string, object>
    {
        { "example", "value" }
    },
    CreatedAt = 1756844019,
    ExpiresAt = 1756847619
}

---

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

Node Python Go Java C#

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

const result = await auth.impersonation.fetchAllForEmployee({
  employeeEmail: "example@acmeinc.com"
});

if (result.ok) {
  console.log("Impersonation sessions fetched successfully");
  console.log("Sessions found:", result.data.sessions.length);
  result.data.sessions.forEach(session => {
    console.log("Session ID:", session.impersonationSessionId);
  });
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.fetch_all_for_employee(
    employee_email="example@acmeinc.com"
)

if is_ok(result):
    print("Impersonation sessions fetched successfully")
    print(f"Sessions found: {len(result.data.sessions)}")
    for session in result.data.sessions:
        print(f"Session ID: {session.impersonation_session_id}")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Impersonation.FetchAllForEmployee(ctx, byo.FetchAllImpersonationSessionsForEmployeeCommand{
    EmployeeEmail: "example@acmeinc.com",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Sessions found: %d\n", len(result.Sessions))

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

FetchAllImpersonationSessionsForEmployeeCommand command = FetchAllImpersonationSessionsForEmployeeCommand.builder()
    .employeeEmail("example@acmeinc.com")
    .build();

try {
    FetchAllImpersonationSessionsForEmployeeResponse response = client.impersonation.fetchAllForEmployee(command);
    System.out.println("Impersonation sessions fetched successfully");
    System.out.println("Sessions found: " + response.getSessions().size());
    for (ImpersonationSessionInfo session : response.getSessions()) {
        System.out.println("Session ID: " + session.getImpersonationSessionId());
    }
} catch (FetchAllImpersonationSessionsForEmployeeException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new FetchAllImpersonationSessionsForEmployeeCommand
{
    EmployeeEmail = "example@acmeinc.com"
};

try
{
    var response = await client.Impersonation.FetchAllForEmployeeAsync(command);
    Console.WriteLine("Impersonation sessions fetched successfully");
    Console.WriteLine($"Sessions found: {response.Sessions.Count}");
    foreach (var session in response.Sessions)
    {
        Console.WriteLine($"Session ID: {session.ImpersonationSessionId}");
    }
}
catch (FetchAllImpersonationSessionsForEmployeeException e)
{
    Console.WriteLine($"Error: {e.Message}");
}

Response

{
  ok: true,
  data: {
    sessions: [
      {
        impersonationSessionId: "L8piQvaIeYoAI6Hl3Rct7F",
        employeeEmail: "example@acmeinc.com",
        targetUserId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
        metadata: {
          "example": "value"
        },
        createdAt: 1756844019,
        expiresAt: 1756847619
      }
    ]
  }
}

Result(
    data=FetchAllImpersonationSessionsForEmployeeResponse(
        sessions=[
            ImpersonationSessionInfo(
                impersonation_session_id="L8piQvaIeYoAI6Hl3Rct7F",
                employee_email="example@acmeinc.com",
                target_user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
                metadata={
                    "example": "value"
                },
                created_at=1756844019,
                expires_at=1756847619
            )
        ]
    )
)

byo.FetchAllImpersonationSessionsForEmployeeResponse{
    Sessions: []byo.ImpersonationSessionInfo{
        {
            ImpersonationSessionID: "L8piQvaIeYoAI6Hl3Rct7F",
            EmployeeEmail:          "example@acmeinc.com",
            TargetUserID:           "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            CreatedAt:              1756844019,
            ExpiresAt:              1756847619,
        },
    },
}

FetchAllImpersonationSessionsForEmployeeResponse(
    sessions=[
        ImpersonationSessionInfo(
            impersonationSessionId="L8piQvaIeYoAI6Hl3Rct7F",
            employeeEmail="example@acmeinc.com",
            targetUserId="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            metadata={example=value},
            createdAt=1756844019,
            expiresAt=1756847619
        )
    ]
)

FetchAllImpersonationSessionsForEmployeeResponse
{
    Sessions = [
        ImpersonationSessionInfo
        {
            ImpersonationSessionId = "L8piQvaIeYoAI6Hl3Rct7F",
            EmployeeEmail = "example@acmeinc.com",
            TargetUserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            Metadata = {"example": "value"},
            CreatedAt = 1756844019,
            ExpiresAt = 1756847619
        }
    ]
}

---

Fetch All Impersonation Sessions for User

Fetches all active impersonation sessions for a user.

Arguments

userId string required

The ID of the user whose impersonation sessions are to be fetched

---

Successful Response

sessions Array<ImpersonationSessionInfo>

List of active impersonation sessions for the user

---

Error Types

UnexpectedError

An unexpected error occurred during the operation

Node Python Go Java C#

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

const result = await auth.impersonation.fetchAllForUser({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
});

if (result.ok) {
  console.log("Impersonation sessions fetched successfully");
  console.log("Sessions found:", result.data.sessions.length);
  result.data.sessions.forEach(session => {
    console.log("Employee:", session.employeeEmail);
  });
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.fetch_all_for_user(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492"
)

if is_ok(result):
    print("Impersonation sessions fetched successfully")
    print(f"Sessions found: {len(result.data.sessions)}")
    for session in result.data.sessions:
        print(f"Employee: {session.employee_email}")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Impersonation.FetchAllForUser(ctx, byo.FetchAllImpersonationSessionsForUserCommand{
    UserID: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Sessions found: %d\n", len(result.Sessions))

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

FetchAllImpersonationSessionsForUserCommand command = FetchAllImpersonationSessionsForUserCommand.builder()
    .userId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .build();

try {
    FetchAllImpersonationSessionsForUserResponse response = client.impersonation.fetchAllForUser(command);
    System.out.println("Impersonation sessions fetched successfully");
    System.out.println("Sessions found: " + response.getSessions().size());
    for (ImpersonationSessionInfo session : response.getSessions()) {
        System.out.println("Employee: " + session.getEmployeeEmail());
    }
} catch (FetchAllImpersonationSessionsForUserException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new FetchAllImpersonationSessionsForUserCommand
{
    UserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
};

try
{
    var response = await client.Impersonation.FetchAllForUserAsync(command);
    Console.WriteLine("Impersonation sessions fetched successfully");
    Console.WriteLine($"Sessions found: {response.Sessions.Count}");
    foreach (var session in response.Sessions)
    {
        Console.WriteLine($"Employee: {session.EmployeeEmail}");
    }
}
catch (FetchAllImpersonationSessionsForUserException e)
{
    Console.WriteLine($"Error: {e.Message}");
}

Response

{
  ok: true,
  data: {
    sessions: [
      {
        impersonationSessionId: "L8piQvaIeYoAI6Hl3Rct7F",
        employeeEmail: "example@acmeinc.com",
        targetUserId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
        metadata: {
          "example": "value"
        },
        createdAt: 1756844019,
        expiresAt: 1756847619
      }
    ]
  }
}

Result(
    data=FetchAllImpersonationSessionsForUserResponse(
        sessions=[
            ImpersonationSessionInfo(
                impersonation_session_id="L8piQvaIeYoAI6Hl3Rct7F",
                employee_email="example@acmeinc.com",
                target_user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
                metadata={
                    "example": "value"
                },
                created_at=1756844019,
                expires_at=1756847619
            )
        ]
    )
)

byo.FetchAllImpersonationSessionsForUserResponse{
    Sessions: []byo.ImpersonationSessionInfo{
        {
            ImpersonationSessionID: "L8piQvaIeYoAI6Hl3Rct7F",
            EmployeeEmail:          "example@acmeinc.com",
            TargetUserID:           "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            CreatedAt:              1756844019,
            ExpiresAt:              1756847619,
        },
    },
}

FetchAllImpersonationSessionsForUserResponse(
    sessions=[
        ImpersonationSessionInfo(
            impersonationSessionId="L8piQvaIeYoAI6Hl3Rct7F",
            employeeEmail="example@acmeinc.com",
            targetUserId="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            metadata={example=value},
            createdAt=1756844019,
            expiresAt=1756847619
        )
    ]
)

FetchAllImpersonationSessionsForUserResponse
{
    Sessions =
    [
        ImpersonationSessionInfo
        {
            ImpersonationSessionId = "L8piQvaIeYoAI6Hl3Rct7F",
            EmployeeEmail = "example@acmeinc.com",
            TargetUserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            Metadata = { "example": "value" },
            CreatedAt = 1756844019,
            ExpiresAt = 1756847619
        }
    ]
}

---

Fetch All Active Impersonation Sessions

Fetches all active impersonation sessions. Can filter by employee email or by target user ID.

Arguments

pagingToken string

Returned by a previous call to fetch the next page of results

employeeEmail string

The email of the employee whose impersonation sessions are to be fetched

targetUserId string

The ID of the user whose impersonation sessions are to be fetched

---

Successful Response

sessions Array<ImpersonationSessionInfo>

List of active impersonation sessions

nextPagingToken string

Token to fetch the next page of results

hasMoreResults boolean

Indicates if there are more results to fetch

---

Error Types

InvalidPagingToken

The provided paging token is invalid

UnexpectedError

An unexpected error occurred during the operation

Node Python Go Java C#

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

const result = await auth.impersonation.fetchAllActive({
  pagingToken: "eyJsYXN0X2NyZWF0...",
  employeeEmail: "example@acmeinc.com",
  targetUserId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
});

if (result.ok) {
  console.log("Impersonation sessions fetched successfully");
  console.log("Sessions found:", result.data.sessions.length);
  console.log("Has more results:", result.data.hasMoreResults);
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.fetch_all_active(
    paging_token="eyJsYXN0X2NyZWF0...",
    employee_email="example@acmeinc.com",
    target_user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492"
)

if is_ok(result):
    print("Impersonation sessions fetched successfully")
    print(f"Sessions found: {len(result.data.sessions)}")
    print(f"Has more results: {result.data.has_more_results}")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Impersonation.FetchAllActive(ctx, byo.FetchAllActiveImpersonationSessionsCommand{
    PagingToken:   byo.String("eyJsYXN0X2NyZWF0..."),
    EmployeeEmail: byo.String("example@acmeinc.com"),
    TargetUserID:  byo.String("1189c444-8a2d-4c41-8b4b-ae43ce79a492"),
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.HasMoreResults)

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

FetchAllActiveImpersonationSessionsCommand command = FetchAllActiveImpersonationSessionsCommand.builder()
    .pagingToken("eyJsYXN0X2NyZWF0...")
    .employeeEmail("example@acmeinc.com")
    .targetUserId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .build();

try {
    FetchAllActiveImpersonationSessionsResponse response = client.impersonation.fetchAllActive(command);
    System.out.println("Impersonation sessions fetched successfully");
    System.out.println("Sessions found: " + response.getSessions().size());
    System.out.println("Has more results: " + response.getHasMoreResults());
} catch (FetchAllActiveImpersonationSessionsException.InvalidPagingToken e) {
    System.out.println("Invalid paging token");
} catch (FetchAllActiveImpersonationSessionsException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new FetchAllActiveImpersonationSessionsCommand
{
    PagingToken = "eyJsYXN0X2NyZWF0...",
    EmployeeEmail = "example@acmeinc.com",
    TargetUserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
};

try
{
    var response = await client.Impersonation.FetchAllActiveAsync(command);
    Console.WriteLine("Impersonation sessions fetched successfully");
    Console.WriteLine($"Sessions found: {response.Sessions.Count}");
    Console.WriteLine($"Has more results: {response.HasMoreResults}");
}
catch (FetchAllActiveImpersonationSessionsException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    sessions: [
      {
        impersonationSessionId: "L8piQvaIeYoAI6Hl3Rct7F",
        employeeEmail: "example@acmeinc.com",
        targetUserId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
        metadata: {
          "example": "value"
        },
        createdAt: 1756844019,
        expiresAt: 1756847619
      }
    ],
    nextPagingToken: "eyJsYXN0X2NyZWF0ZSI6I...",
    hasMoreResults: true
  }
}

Result(
    data=FetchAllActiveImpersonationSessionsResponse(
        sessions=[
            ImpersonationSessionInfo(
                impersonation_session_id="L8piQvaIeYoAI6Hl3Rct7F",
                employee_email="example@acmeinc.com",
                target_user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
                metadata={
                    "example": "value"
                },
                created_at=1756844019,
                expires_at=1756847619
            )
        ],
        next_paging_token="eyJsYXN0X2NyZWF0ZSI6I...",
        has_more_results=True
    )
)

byo.FetchAllActiveImpersonationSessionsResponse{
    Sessions: []byo.ImpersonationSessionInfo{
        {
            ImpersonationSessionID: "L8piQvaIeYoAI6Hl3Rct7F",
            EmployeeEmail:          "example@acmeinc.com",
            TargetUserID:           "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            CreatedAt:              1756844019,
            ExpiresAt:              1756847619,
        },
    },
    NextPagingToken: byo.String("eyJsYXN0X2NyZWF0ZSI6I..."),
    HasMoreResults:  true,
}

FetchAllActiveImpersonationSessionsResponse(
    sessions=[
        ImpersonationSessionInfo(
            impersonationSessionId="L8piQvaIeYoAI6Hl3Rct7F",
            employeeEmail="example@acmeinc.com",
            targetUserId="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            metadata={example=value},
            createdAt=1756844019,
            expiresAt=1756847619
        )
    ],
    nextPagingToken="eyJsYXN0X2NyZWF0ZSI6I...",
    hasMoreResults=true
)

FetchAllActiveImpersonationSessionsResponse {
    Sessions = [
        ImpersonationSessionInfo {
            ImpersonationSessionId = "L8piQvaIeYoAI6Hl3Rct7F",
            EmployeeEmail = "example@acmeinc.com",
            TargetUserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            Metadata = { "example": "value" },
            CreatedAt = 1756844019,
            ExpiresAt = 1756847619
        }
    ],
    NextPagingToken = "eyJsYXN0X2NyZWF0ZSI6I...",
    HasMoreResults = true
}

---

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

Node Python Go Java C#

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

const result = await auth.impersonation.invalidateById({
  impersonationSessionId: "L8piQvaIeYo...",
});

if (result.ok) {
  console.log("Impersonation session invalidated successfully");
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.invalidate_by_id(
    impersonation_session_id="L8piQvaIeYo..."
)

if is_ok(result):
    print("Impersonation session invalidated successfully")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

_, err = client.Impersonation.InvalidateByID(ctx, byo.InvalidateImpersonationSessionByIdCommand{
    ImpersonationSessionID: "L8piQvaIeYo...",
})
if err != nil {
    log.Fatal(err)
}

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

InvalidateImpersonationSessionByIdCommand command = InvalidateImpersonationSessionByIdCommand.builder()
    .impersonationSessionId("L8piQvaIeYo...")
    .build();

try {
    InvalidateImpersonationSessionByIdResponse response = client.impersonation.invalidateById(command);
    System.out.println("Impersonation session invalidated successfully");
} catch (InvalidateImpersonationSessionByIdException.SessionNotFound e) {
    System.out.println("Session not found");
} catch (InvalidateImpersonationSessionByIdException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new InvalidateImpersonationSessionByIdCommand
{
    ImpersonationSessionId = "L8piQvaIeYo..."
};

try
{
    var response = await client.Impersonation.InvalidateByIdAsync(command);
    Console.WriteLine("Impersonation session invalidated successfully");
}
catch (InvalidateImpersonationSessionByIdException.SessionNotFound)
{
    Console.WriteLine("Session not found");
}
catch (InvalidateImpersonationSessionByIdException e)
{
    Console.WriteLine($"Error: {e.Message}");
}

Response

{
  ok: true,
  data: {}
}

Result(
    data=InvalidateImpersonationSessionByIdResponse()
)

byo.InvalidateImpersonationSessionByIdResponse{}

InvalidateImpersonationSessionByIdResponse()

InvalidateImpersonationSessionByIdResponse()

---

Invalidate Impersonation Session by Token

Invalidates (deletes) an impersonation session by session token.

Arguments

impersonationSessionToken string required

The impersonation session token 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

Node Python Go Java C#

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

const result = await auth.impersonation.invalidateByToken({
  impersonationSessionToken: "impersonate_L8piQvaIeYo...",
});

if (result.ok) {
  console.log("Impersonation session invalidated successfully");
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.invalidate_by_token(
    impersonation_session_token="impersonate_L8piQvaIeYo..."
)

if is_ok(result):
    print("Impersonation session invalidated successfully")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

_, err = client.Impersonation.InvalidateByToken(ctx, byo.InvalidateImpersonationSessionByTokenCommand{
    ImpersonationSessionToken: "impersonate_L8piQvaIeYo...",
})
if err != nil {
    log.Fatal(err)
}

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

InvalidateImpersonationSessionByTokenCommand command = InvalidateImpersonationSessionByTokenCommand.builder()
    .impersonationSessionToken("impersonate_L8piQvaIeYo...")
    .build();

try {
    InvalidateImpersonationSessionByTokenResponse response = client.impersonation.invalidateByToken(command);
    System.out.println("Impersonation session invalidated successfully");
} catch (InvalidateImpersonationSessionByTokenException.SessionNotFound e) {
    System.out.println("Session not found");
} catch (InvalidateImpersonationSessionByTokenException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new InvalidateImpersonationSessionByTokenCommand
{
    ImpersonationSessionToken = "impersonate_L8piQvaIeYo..."
};

try
{
    var response = await client.Impersonation.InvalidateByTokenAsync(command);
    Console.WriteLine("Impersonation session invalidated successfully");
}
catch (InvalidateImpersonationSessionByTokenException e)
{
    Console.WriteLine($"Error: {e.Message}");
}

Response

{
  ok: true,
  data: {}
}

Result(
    data=InvalidateImpersonationSessionByTokenResponse()
)

byo.InvalidateImpersonationSessionByTokenResponse{}

InvalidateImpersonationSessionByTokenResponse()

InvalidateImpersonationSessionByTokenResponse()

---

Invalidate All Impersonation Sessions for Employee

Invalidates (deletes) all impersonation sessions for an employee.

Arguments

employeeEmail string required

The email of the employee whose impersonation sessions are to be invalidated

---

Successful Response

sessionsInvalidated number

The number of sessions that were invalidated

---

Error Types

UnexpectedError

An unexpected error occurred during the operation

Node Python Go Java C#

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

const result = await auth.impersonation.invalidateAllForEmployee({
  employeeEmail: "example@acmeinc.com"
});

if (result.ok) {
  console.log("Impersonation sessions invalidated successfully");
  console.log("Sessions invalidated:", result.data.sessionsInvalidated);
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.invalidate_all_for_employee(
    employee_email="example@acmeinc.com"
)

if is_ok(result):
    print("Impersonation sessions invalidated successfully")
    print(f"Sessions invalidated: {result.data.sessions_invalidated}")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Impersonation.InvalidateAllForEmployee(ctx, byo.InvalidateAllImpersonationSessionsForEmployeeCommand{
    EmployeeEmail: "example@acmeinc.com",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.SessionsInvalidated)

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

InvalidateAllImpersonationSessionsForEmployeeCommand command = InvalidateAllImpersonationSessionsForEmployeeCommand.builder()
    .employeeEmail("example@acmeinc.com")
    .build();

try {
    InvalidateAllImpersonationSessionsForEmployeeResponse response = client.impersonation.invalidateAllForEmployee(command);
    System.out.println("Impersonation sessions invalidated successfully");
    System.out.println("Sessions invalidated: " + response.getSessionsInvalidated());
} catch (InvalidateAllImpersonationSessionsForEmployeeException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new InvalidateAllImpersonationSessionsForEmployeeCommand
{
    EmployeeEmail = "example@acmeinc.com"
};

try
{
    var response = await client.Impersonation.InvalidateAllForEmployeeAsync(command);
    Console.WriteLine("Impersonation sessions invalidated successfully");
    Console.WriteLine($"Sessions invalidated: {response.SessionsInvalidated}");
}
catch (InvalidateAllImpersonationSessionsForEmployeeException e)
{
    Console.WriteLine($"Error: {e.Message}");
}

Response

{
  ok: true,
  data: {
    sessionsInvalidated: 3
  }
}

Result(
    data=InvalidateAllImpersonationSessionsForEmployeeResponse(
        sessions_invalidated=3
    )
)

byo.InvalidateAllImpersonationSessionsForEmployeeResponse{
    SessionsInvalidated: 3,
}

InvalidateAllImpersonationSessionsForEmployeeResponse(
    sessionsInvalidated=3
)

InvalidateAllImpersonationSessionsForEmployeeResponse
{
    SessionsInvalidated = 3
}

---

Invalidate All Impersonation Sessions for User

Invalidates (deletes) all impersonation sessions for a user.

Arguments

userId string required

The ID of the user whose impersonation sessions are to be invalidated

---

Successful Response

sessionsInvalidated number

The number of sessions that were invalidated

---

Error Types

UnexpectedError

An unexpected error occurred during the operation

Node Python Go Java C#

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

const result = await auth.impersonation.invalidateAllForUser({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
});

if (result.ok) {
  console.log("Impersonation sessions invalidated successfully");
  console.log("Sessions invalidated:", result.data.sessionsInvalidated);
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

client = create_client(url=url, integration_key=integration_key)

result = await client.impersonation.invalidate_all_for_user(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492"
)

if is_ok(result):
    print("Impersonation sessions invalidated successfully")
    print(f"Sessions invalidated: {result.data.sessions_invalidated}")
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Impersonation.InvalidateAllForUser(ctx, byo.InvalidateAllImpersonationSessionsForUserCommand{
    UserID: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.SessionsInvalidated)

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

InvalidateAllImpersonationSessionsForUserCommand command = InvalidateAllImpersonationSessionsForUserCommand.builder()
    .userId("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
    .build();

try {
    InvalidateAllImpersonationSessionsForUserResponse response = client.impersonation.invalidateAllForUser(command);
    System.out.println("Impersonation sessions invalidated successfully");
    System.out.println("Sessions invalidated: " + response.getSessionsInvalidated());
} catch (InvalidateAllImpersonationSessionsForUserException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

var command = new InvalidateAllImpersonationSessionsForUserCommand
{
    UserId = "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
};

try
{
    var response = await client.Impersonation.InvalidateAllForUserAsync(command);
    Console.WriteLine("Impersonation sessions invalidated successfully");
    Console.WriteLine($"Sessions invalidated: {response.SessionsInvalidated}");
}
catch (InvalidateAllImpersonationSessionsForUserException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    sessionsInvalidated: 2
  }
}

Result(
    data=InvalidateAllImpersonationSessionsForUserResponse(
        sessions_invalidated=2
    )
)

byo.InvalidateAllImpersonationSessionsForUserResponse{
    SessionsInvalidated: 2,
}

InvalidateAllImpersonationSessionsForUserResponse(
    sessionsInvalidated=2
)

InvalidateAllImpersonationSessionsForUserResponse
{
    SessionsInvalidated = 2
}

---

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. We strongly recommend keeping this enabled for security reasons. Defaults to true.

who_can_impersonate object

This section defines who is allowed to impersonate other users. Note that the most restrictive rule applies if multiple are specified. Default is that no one can impersonate anyone.

• allowed_employee_emails: List of specific employee emails allowed to impersonate users
• allowed_employee_domains: List of allowed email domains for employees who can impersonate users
• allow_all_because_i_will_gate_access_myself: Set to true if you will gate access yourself

JSONC

{
    // Enable or disable user impersonation feature globally.
    "enabled": false,

    // Duration for which an impersonation session remains valid (in seconds).
    "impersonation_duration_secs": 3600, // 1 hour

    // Whether to restrict impersonation sessions to the IP address of the original user.
    // We strongly recommend keeping this enabled for security reasons.
    "disallow_ip_address_changes": true,

    // This section defines who is allowed to impersonate other users.
    // Note that the most restrictive rule applies if multiple are specified. So if you have
    // both specific emails and domains, only those specific emails will be allowed.
    // Default is that no one can impersonate anyone.
    "who_can_impersonate": {
        // List of specific employee emails allowed to impersonate users.
        // "allowed_employee_emails": ["joe@example.com"],

        // List of allowed email domains for employees who can impersonate users.
        // "allowed_employee_domains": ["example.com"],

        // If you set this to true, you'll want to make sure you are
        // protecting calls to createImpersonationSession yourself
        // "allow_all_because_i_will_gate_access_myself": false
    }
}