---
title: "How do I configure LUSID to use a different API access token issuer?"
slug: "how-do-i-configure-lusid-to-use-a-different-api-access-token-issuer"
updated: 2025-08-21T12:05:13Z
published: 2025-08-21T12:05:13Z
canonical: "support.lusid.com/how-do-i-configure-lusid-to-use-a-different-api-access-token-issuer"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How do I configure LUSID to use a different API access token issuer?

You can use the [ExternalTokenIssuer](https://www.lusid.com/docs/api/identity/endpoints/external-token-issuers/CreateExternalTokenIssuer) API to configure LUSID to use API access tokens for your own identity provider (IDP) for all requests in your LUSID domain. You can configure up to five different external token issuers.

> [!TIP]
> Prerequisites
> 
> [Contact us](https://www.finbourne.com/contact/) to provision your LUSID domain with access to the `ExternalTokenIssuer` API endpoints.

To set up an external token issuer, call the [CreateExternalTokenIssuer](https://www.lusid.com/docs/api/identity/endpoints/external-token-issuers/CreateExternalTokenIssuer) API, passing in the following:

- A `code` that uniquely identifies the configuration
- As supplied by your token provider:

Note the `issuer`/`audience` combination must be unique within your LUSID domain.
  - An `issuer` URL
  - An `audience` string
- A friendly `description`
- A `logoutUrl` for LUSID to redirect users to when they log out; this defaults to the LUSID logout screen if you do not provide a value
- A collection of `claimMappings` to map the token fields required by LUSID to your external token fields, including a field name mapping for:

> [!NOTE]
> Note
> 
> You can set a `claimMappings` field name, excluding `groups`, to an explicit value by wrapping the value in `““` characters, for example `userType = "Personal"`.
  - `userId` for unique LUSID [user IDs](/v1/docs/what-is-a-user-id-and-how-do-i-discover-one)
  - The `login` email address for each LUSID account (a LUSID username; it must be unique within your LUSID domain)
  - The `email` address for each LUSID account (this should be the same as the `login` unless you’re configuring a [service user account](/v1/docs/how-do-i-set-up-a-service-user-account))
  - The `firstName` of the user
  - The `lastName` of the user
  - The `userType` ([personal or service](/v1/docs/what-are-a-personal-user-and-a-service-user))
  - Optionally, `groups` for mapping to LUSID [roles](/v1/docs/what-is-a-role)

For example, if you have the following external token fields and mappings…

| LUSID field | External token issuer field example |
| --- | --- |
| `userId` | `uniqueId` |
| `login` | `username` |
| `email` | `email` |
| `firstName` | `givenName` |
| `LastName` | `surname` |
| `userType` | `"Personal"` |
| `groups` | `role` |

…you might send the following request:

```json
curl -X POST 'https://<your-domain>.lusid.com/identity/api/externaltokenissuers' 
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
{
  "code": "Acme-External-Token-Issuer",
  "issuer": "https://auth.acme.com",
  "audience": "api.acme-app.com",
  "description": "External Token Issuer definition to allow matching Acme Co. authentication tokens to LUSID API access tokens",
  "claimMappings": {
    "userId": "uniqueId",
    "login": "username",
    "email": "email",
    "firstName": "givenName",
    "lastName": "surname",
    "userType": "\"Personal"\",
    "groups": "role"
  },
  "logoutUrl": "https://acme.com/signedout"
}'
```

Once you’ve set up your external token issuer, your users can continue to use LUSID as usual. Behind the scenes, LUSID obtains an access token for each request from your configured identity provider.

> [!NOTE]
> Note
> 
> If using LUSID’s [impersonation feature](/v1/docs/how-do-i-use-the-impersonation-feature), you can continue to use the relevant additional headers in requests as usual.

---

### Troubleshooting

#### `Issuer is invalid` error

If your request fails with the error message `The field Issuer is invalid.`, ensure you have contacted us to express your intent to use an external token issuer. For your security, we only allow approved issuer URLs as inputs for the `Issuer` field.

#### I’m not sure what my `audience` value should be

Audience is supplied by your external token issuer. Please contact your external token provider for help obtaining the required value.