Authentication

Authenticate with the LendWorks Broker API using API keys with scoped permissions.

API Key Authentication

All authenticated endpoints require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer lw_live_xxxxxxxxxxxxxxxx" \
     https://api.lend.works/v1/leads

With the SDK

import { LendWorksClient } from '@lendworks/sdk-node'

const client = new LendWorksClient({
  apiKey: process.env.LENDWORKS_API_KEY,
})

Key Format

API keys follow the format lw_{prefix}_{secret}:

Part	Description	Example
`lw`	Fixed namespace prefix	`lw`
`prefix`	Unique key identifier (used for lookup)	`abc12`
`secret`	Hashed secret (bcrypt, never stored in plaintext)	`xxxxxxxxxxxxxxxx`

The prefix allows key identification in logs and dashboards without exposing the secret.

Key Management

Create and manage API keys in Admin > API Keys. Each key has:

Permission Levels

Level	Allowed Methods	Use Case
`read`	`GET` only	Reporting, dashboards, read-only integrations
`read_write`	`GET`, `POST`, `PATCH`, `PUT`	Most integrations — create and update resources
`full`	All methods including `DELETE`	Administrative integrations

Attempting a disallowed method returns 403 Forbidden:

{
  "errors": [
    {
      "code": "FORBIDDEN",
      "message": "API key permission level 'read' does not allow POST requests"
    }
  ]
}

Rate Limit Tiers

Each key is assigned a tier that controls request limits:

Tier	Requests/min	Use Case
`basic`	100	Development, testing
`standard`	1,000	Production integrations
`premium`	10,000	High-volume production

See Rate Limits for details on headers and quota enforcement.

Key Rotation

LendWorks supports zero-downtime key rotation:

Navigate to Admin > API Keys and click Rotate on an existing key
A new key is generated immediately
The old key enters a grace period (configurable, default 24 hours)
Both keys work during the grace period
The old key is automatically revoked when the grace period expires

During the grace period, requests using the old key receive deprecation headers:

X-Api-Key-Deprecated: true
X-Api-Key-Grace-Period-Ends: 2025-01-16T10:00:00Z

Multi-Tenancy

API keys are scoped to a single organization. All resources returned by the API are automatically filtered to the organization that owns the key — you never need to pass an orgId parameter.

Error Responses

Status	Code	Description
401	`API_KEY_REQUIRED`	No `Authorization` header provided
401	`INVALID_API_KEY`	Key not found or secret doesn't match
401	`API_KEY_REVOKED`	Key has been revoked (past grace period)
401	`API_KEY_EXPIRED`	Key has expired
403	`FORBIDDEN`	Key doesn't have permission for this method

Correlation IDs

Every response includes an X-Request-Id header for request tracing:

X-Request-Id: 550e8400-e29b-41d4-a716-446655440000

Include this ID in support requests for faster debugging. You can also send your own X-Request-Id header to propagate your internal correlation IDs.

Security Best Practices

Store API keys in environment variables, never in source code
Use read permission keys for reporting — minimize blast radius
Rotate keys regularly and monitor the deprecation headers
Use separate keys for development and production environments
Set up IP allowlists in your organization settings for additional security

Authentication

On this page