Authentication
Authenticate server-to-server integrations with OAuth 2.0 client credentials, least-privilege scopes, tenant isolation, and explicit approval permissions.
Client-credentials flow
LendEasy uses OAuth 2.0 client credentials for machine-to-machine access. Credentials belong to one tenant and one environment. Exchange them only from a trusted backend:
curl https://auth.lendeasy.ai/oauth2/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scope=lending:read lending:write"{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "lending:read lending:write"
}Send the token on every API request:
curl https://sandbox.api.lendeasy.ai/v1/loans/7204/summary \
-H "Authorization: Bearer $TOKEN" \
-H "LendEasy-Tenant: demo-lender"Alongside the token, every API call carries the tenant selector header LendEasy-Tenant — lowercase letters, digits, and hyphens, for example demo-lender. The token must be entitled to the tenant it names; see Environments for how tenants and environments are provisioned.
Token handling
Cache the access token until shortly before expiry. A practical strategy is to refresh when less than 10% of expires_in remains and to serialize refreshes so a busy service does not create a token stampede.
| Rule | Why it matters |
|---|---|
| Keep secrets in a secrets manager. | Source control, logs, and client applications are not secret stores. |
| Use a different client per workload. | Revocation and least privilege stay narrow. |
| Never log tokens or client secrets. | They authorize API calls until revoked or expired. |
| Do not decode a token to drive business logic. | Claims may evolve; API responses are the contract. |
| Rotate credentials without changing client IDs. | Overlapping secrets allow zero-downtime rotation. |
Scopes and endpoint permissions
Scopes establish the broad surface a client may enter. The endpoint’s named permission then determines the exact operation it may perform.
| Scope | Typical use |
|---|---|
servicing:read |
Cases, tasks, decisions, interactions, and evidence metadata. |
servicing:write |
Create cases, interactions, promises, and action requests. |
lending:read |
Customers, products, loans, schedules, payments, and statements. |
lending:write |
Origination, customer changes, money movement, and governed commands. |
actions:approve |
Second-person approval for configured high-impact actions. |
Each API page shows its endpoint permission beside the method and path. A token may contain the broad lending:write scope while still lacking APPROVE_LMS_FUNDING or APPROVE_RESCHEDULELOAN.
Tenant and environment isolation
Each call names its tenant with the LendEasy-Tenant header, and the issued access token must be entitled to that tenant — the header selects, the token authorizes. A resource from another tenant behaves as unavailable. Sandbox tokens are rejected by Production and Production tokens are rejected by Sandbox.
| Response | Meaning | Recovery |
|---|---|---|
401 Unauthorized |
Token is absent, expired, malformed, or issued for another environment. | Refresh once, then stop and surface the authentication failure. |
403 Forbidden |
The client is authenticated but lacks the required scope or permission. | Change the client’s assigned role; retries do not help. |
404 Not Found |
The resource does not exist or is outside the caller’s tenant visibility. | Check the opaque ID and environment without probing other tenants. |
Approval separation
Authentication never bypasses maker-checker. When an operation requires approval, the creator and approver must be distinct eligible actors. Approval records preserve the actor, decision, policy version, request hash, and time. See Access control & maker-checker.