How do I impersonate another user or role?

  • Updated on Feb 6, 2025
  • Published on Jan 29, 2025

With LUSID’s impersonation feature, you can allow particular privileged accounts to impersonate another user or role when making a request to APIs in the FINBOURNE platform. For example, you could grant a service user account impersonation privileges that your business’s trusted subsystem can use to operate on behalf of a user in LUSID.

To enable impersonation in LUSID, contact us. Once enabled, to use the impersonation feature:

  1. Set up a service user account with impersonation privileges.

  2. Send an impersonated API request.

To use the impersonation feature, you must create a service user account and assign them a role containing the correct policy. To do this:

  1. Sign in to the LUSID web app with the credentials of a LUSID administrator.

  2. From the top left menu, navigate to Identity and Access > Roles. Create a new role allow-user-impersonation with the assigned system policy lusid-system-allow-user-impersonation.

  3. From the top left menu, navigate to Identity and Access > Users. Create a service user account with the following assigned roles:

    • allow-user-impersonation

    • lusid-administrator

    You can also assign the service user additional roles of your choice. See how to assign a role to a user.

    Note

    When creating the service user account, you must specify a Login. We recommend you specify a value that explicitly indicates it is your impersonating user, for example impersonator@acme.com.

  4. Create a Personal Access Token (PAT) for the service user. All impersonated requests will require this PAT, so ensure you store the PAT securely.

A service user with impersonation privileges can send a FINBOURNE platform API request with additional headers to make the request as either:

To impersonate an existing LUSID user and their assigned roles in a request, you must include one of the following HTTP headers:

  • X-LUSID-Run-As-User, specifying the user ID you intend to impersonate. For example, to call the ListPortfolios API as Jane Smith whose user ID is 00um073pwk8WMVC8Z2p7, you might send the following request:

    curl -X GET "https://<your-domain>.lusid.com/api/api/portfolios?limit=3"
  -H "X-LUSID-Run-As-User: 00um073pwk8WMVC8Z2p7"
  -H "Authorization: Bearer <service-user-personal-access-token>"
    Shell

  • X-LUSID-Run-As-Login, specifying the unique login of the user you intend to impersonate. For example, to call the ListPortfolios API as Jane Smith whose login is jane.smith@acme.com, you might send the following request:

    curl -X GET "https://<your-domain>.lusid.com/api/api/portfolios?limit=3"
  -H "X-LUSID-Run-As-Login: jane.smith@acme.com"
  -H "Authorization: Bearer <service-user-personal-access-token>"
    Shell

To impersonate one or more roles as a non-existent user in a request, you must include the following HTTP headers:

  • X-LUSID-Run-As-User, specifying the user ID of a user that does not exist in LUSID. LUSID will log activities as this user ID.

    Note

    You can use any user ID value for non-existent impersonated users, however the value should not contain personally identifying information.

  • X-LUSID-Run-As-Roles, specifying a comma-separated list of roles that grant access to the requested features and data.

    Note

    You must prefix roles that are not in the default scope with <scope>:. For example, the lusid-administrator role is in the scope LUSID_SYSTEM, therefore you must specify the value LUSID_SYSTEM:lusid-administrator. You can call the ListRoles API to view role scopes.

For example, to call the ListPortfolios API as an impersonating user with the granting roles portfolio-manager-UK and portfolio-manager-US, you might send the following request:

curl -X GET "https://<your-domain>.lusid.com/api/api/portfolios?limit=3"
  -H "X-LUSID-Run-As-User: my-impersonated-user"
  -H "X-LUSID-Run-As-Roles: portfolio-manager-UK, portfolio-manager-US"
  -H "Authorization: Bearer <service-user-personal-access-token>"
Shell

Note the following:

  • The specified roles must grant access to both the required data and feature policies for the request. Read more.

  • You must use the service user’s generated PAT as the bearer token for an impersonating call.

  • You cannot create or use an impersonated user’s PAT. You may only use the service user’s PAT.

When you make an impersonated request, the request logs contain the following values:

  • The user ID of the impersonated user.

  • The impersonatingUser ID.

Note

Currently, you can only retrieve the impersonatingUser ID via the Insights API, for example by calling the GetRequestLog endpoint.

When you use the X-LUSID-Run-As-Roles HTTP header, you must prefix roles that are not in the default scope with <scope>:. You can call the ListRoles API to view role scopes.

See Impersonating one or more roles.