Authentication

LendAPI has two kinds of callers. Systems call the REST API with an API key, which identifies your tenant (your LendAPI workspace) and decides whether the call uses Sandbox or Production. People sign in to the dashboard with their email and password, or with single sign-on, and you can require an SMS code at sign-in with two-factor authentication. This guide covers both.

Key concepts

• API key: a secret string that authenticates API requests for your tenant. Anyone who has it can call the API as your tenant, so treat it like a password.
• Live key: a key that starts with live_. Requests made with it read and write your Production data.
• Test key: a key that starts with test_. Requests made with it read and write your Sandbox data.
• Key name: a label you give the key so you can tell keys apart, for example "Website" or "LOS integration".
• Status: whether a key is enabled. A disabled key is rejected immediately.

Use the API

How API keys work

Every API request must include your key in the Authorization header, prefixed with Bearer:

Authorization: Bearer live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

LendAPI looks up the key, finds the tenant it belongs to, and runs the request against that tenant's data only. The key's prefix chooses the environment: live_ keys use Production and test_ keys use Sandbox. See Sandbox and Live.

The API base URL is the same for both environments:

https://app.lendapi.com/api/v1/

Create an API key

API keys belong to the environment you are in when you create them. To create a test key, switch the environment selector in the top bar to Sandbox first. To create a live key, switch it to Production.

1. Open the profile menu in the top-right corner and select Settings.
2. Open the API tab. The API Keys page lists your existing keys.
3. Click API Key (the button with the plus icon).
4. In the Add API Key dialog, enter a Key Name and click Add Key.
5. The new key appears in the list. Use View Key to show it and Copy Key to copy it.

🚧

Plan required

Creating API keys requires an active, paid LendAPI plan. If your plan is not active, the request is refused with the message "Please check your plan."

Make your first request

This example lists the decision trees in your Sandbox environment. Replace the key with your own test key.

curl https://app.lendapi.com/api/v1/decisions/ \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "object": "decision",
  "url": "/v1/decisions",
  "has_more": false,
  "message": "",
  "results": [
    {
      "id": "5c13c1d7-0000-4000-8000-000000000001",
      "title": "Personal loan credit policy",
      "description": "",
      "default": 3,
      "published": true,
      "active": true
    }
  ]
}

See List all Decisions in the API reference for the full schema.

Authentication errors

See API Conventions for the full error format and rate limits.

Disable or rotate a key

Each key has a Status switch on the API Keys page. Turning it off disables the key immediately, and every request using it returns 401. Turning it back on restores access.

To rotate a key without downtime:

1. Create a new key in the same environment.
2. Deploy the new key to your systems.
3. Confirm traffic is using the new key.
4. Turn off the Status switch for the old key.

❗️

Keep keys secret

API keys give full API access to your tenant. Keep them on your servers only. Never put a key in a web page, mobile app, or public code repository. If a key may have leaked, disable it right away and create a replacement.

Dashboard access

Sign in to the dashboard

Team members sign in on the Login to your account page with their email address and password. If they forget their password, they can reset it with the Forgot Password? link.

If your organization has its own identity provider, you can let users sign in through it instead. See Single Sign-On.

What a user can do after signing in depends on their role. See Users and Teams and Roles and Permissions.

Turn on two-factor authentication

Two-factor authentication (2FA) adds a second step to sign-in. After entering the correct password, the user receives a 6-digit confirmation code by SMS at the mobile number on their profile, and enters it to finish signing in. The code expires after 30 minutes. The user can request a new code if it doesn't arrive or has expired.

1. Open the profile menu and select Settings.
2. Open the Security tab.
3. Turn on Two Factor Authentication.
4. Click Save.

The setting applies to the users of the workspace. If your workspace uses branches, users who belong to a branch are also covered by the parent workspace's setting.

Permissions

The API and Security tabs are part of the Settings module. A user needs edit access to the API tab to create or disable keys, and edit access to the Security tab to change 2FA. See Roles and Permissions.

Best practices

• Use one key per integration. Separate keys let you disable one system without affecting others, and the key name tells you which system it belongs to.
• Use test keys until you go live. Build and test against Sandbox with a test_ key. Switch to a live_ key only when you are ready to process real applications.
• Store keys in a secrets manager or environment variables. Never hard-code them.
• Handle 401 and 403 separately. A 401 usually means the key is wrong or disabled. A 403 usually means the header is missing or malformed, or the resource belongs to a different tenant.
• Turn on 2FA for every workspace that handles real applicant data.

Related guides