Single Sign-On

Single sign-on (SSO) lets your team sign in to the LendAPI dashboard with the accounts they already use at work, such as Okta, Microsoft Entra ID or Amazon Cognito. You manage who has access, and which role they get, in your identity provider instead of creating each user by hand in LendAPI.

LendAPI supports SSO over OpenID Connect (OIDC). SAML is not supported.

Key concepts

• Identity provider (IdP): the system that holds your users and passwords, such as Okta, Microsoft Entra ID or Amazon Cognito.
• OIDC application: the app you register in your IdP for LendAPI. It gives you a client ID and client secret.
• Issuer URL: your IdP's base OIDC address. LendAPI reads its discovery document (/.well-known/openid-configuration) to find the sign-in, token and key endpoints.
• Callback URL: the LendAPI address your IdP sends users back to after they sign in. Also called the redirect URI or sign-in redirect URI.
• SSO group: a group your IdP includes in the user's ID token.
• Group mapping: a rule that gives users in an SSO group a specific LendAPI role.

How SSO sign-in works

Users sign in on your identity provider's sign-in page for the LendAPI app. After they sign in, the identity provider sends them back to LendAPI's callback URL, and LendAPI signs them in to the dashboard.

sequenceDiagram
    participant U as User
    participant IdP as Identity provider
    participant L as LendAPI
    U->>IdP: Sign in to the LendAPI app
    IdP->>L: Return to the callback URL with a code
    L->>IdP: Exchange the code for an ID token
    L->>L: Verify token, find or create the user, apply group mapping
    L->>U: Signed in to the dashboard

On each SSO sign-in, LendAPI:

1. Verifies the ID token's signature against your IdP's published keys and checks that it was issued for your client ID.
2. Finds the LendAPI user with the token's email. If none exists, it creates one in your workspace.
3. Reads the user's groups from the token and gives the user the role from the first matching group mapping.

Set it up in the dashboard

Before you start

• You need Settings → Security: Edit in LendAPI (Admins have it).
• Make the change in Live mode. In Sandbox mode, the Security page saves to Sandbox only and does not affect Production sign-in.
• Your IdP must issue an ID token signed with RS256 that contains an email claim.
• Decide which IdP groups should map to which LendAPI roles (see Roles and Permissions).

1. Copy your callback URL

1. Go to Settings → Security.
2. Turn on Single Sign On.
3. Under OIDC Callback URL, copy the URL. It looks like https://<your LendAPI domain>/sso/callback/<workspace ID>.

2. Register LendAPI in your identity provider

In your IdP, create an OIDC web application (authorization code flow, with a client secret) and set:

Then assign the app to the people or groups who should have access, and note the client ID, client secret and issuer URL.

Provider notes:

If users sign in but their group claims don't reach LendAPI, contact LendAPI support.

3. Enter your IdP details in LendAPI

Back in Settings → Security, under OIDC Details of IDP:

1. Provider Name: a label for your IdP, for example Okta.
2. Client ID: from your IdP app.
3. Client Secret: from your IdP app. It is stored encrypted.
4. Issuer URL: your IdP's issuer, with or without https://. LendAPI always uses HTTPS.

4. Map SSO groups to roles

Under SSO Group Mapping, add one row per group:

1. In SSO Group, enter the group name exactly as your IdP sends it. Group names are case-sensitive.
2. In Applicant Role, choose the LendAPI role to give users in that group.
3. Add more rows as needed.

If a user is in several mapped groups, the first matching row wins, so order your rows deliberately.

5. Save and test

1. Click Save on the Security page.
2. In a private browser window, sign in to the LendAPI app through your identity provider.
3. Confirm you land in the LendAPI dashboard with the expected role.

To turn SSO off, switch off Single Sign On and click Save. Your configuration is kept.

After setup

What happens to users

Users created through SSO do not have a LendAPI password. Removing someone from the LendAPI app in your IdP stops them signing in through SSO, but does not disable their LendAPI account; disable it in Settings → Users too. See Users and Teams.

API access

SSO is configured in the dashboard only. It is not part of the public REST API, and it does not affect API keys.

Required permissions

Configuring SSO and two-factor authentication requires Settings → Security: Edit. See Roles and Permissions.

Troubleshooting

Best practices

• Map every group you assign to the app, so every new user gets a role on first sign-in.
• Keep at least one Admin who can sign in with a password in case your IdP is unavailable.
• Order mappings from most to least specific. The first match wins.
• Offboard in both places: remove the user in your IdP and disable them in LendAPI.
• Turn on multi-factor authentication in your IdP for users who sign in with SSO.

Related guides