LendWorksOAuth Scopes
Granular permissions that control what data your app can read and write.
Overview
Scopes define the level of access your app requests from a LendWorks organization. Users see the requested scopes on the consent screen before approving installation. Request only the scopes your app needs — apps requesting excessive permissions are less likely to be approved by users or the marketplace review team.
Available Scopes
Leads
| Scope | Description |
|---|---|
leads:read | View leads, search, and filter by pipeline stage |
leads:write | Create, update, and manage lead pipeline stages |
Applications
| Scope | Description |
|---|---|
applications:read | View lender applications and their statuses |
applications:write | Create and update lender applications |
Lenders
| Scope | Description |
|---|---|
lenders:read | View lender directory and product details |
lenders:write | Create and update lender records and products |
Funded Deals
| Scope | Description |
|---|---|
funded-deals:read | View funded deal records and amounts |
funded-deals:write | Create and update funded deal records |
Commissions
| Scope | Description |
|---|---|
commissions:read | View commission records and summaries |
Analytics
| Scope | Description |
|---|---|
analytics:read | Access KPIs, pipeline analytics, and leaderboards |
Automations
| Scope | Description |
|---|---|
automations:read | View automation templates and execution history |
automations:write | Trigger and cancel automation instances |
Pipeline
| Scope | Description |
|---|---|
pipeline-stages:read | View pipeline stage configuration |
Custom Fields
| Scope | Description |
|---|---|
custom-fields:read | View custom field definitions |
Contacts
| Scope | Description |
|---|---|
contacts:read | View contact records |
contacts:write | Create and update contacts |
Documents
| Scope | Description |
|---|---|
documents:read | View and download documents |
documents:write | Upload and manage documents |
Webhooks
| Scope | Description |
|---|---|
webhooks:manage | Create, update, and delete webhook subscriptions for your app |
App Data
| Scope | Description |
|---|---|
app-data:read | Read from your app's per-org data store |
app-data:write | Write to your app's per-org data store |
Profile
| Scope | Description |
|---|---|
profile:read | View the installing user's basic profile and organization info |
Requesting Scopes
Include scopes as a space-separated string in the OAuth authorization URL:
GET https://auth.lend.works/oauth/authorize
?client_id=lw_app_xxxxxxxxxxxx
&scope=leads:read leads:write webhooks:manage
&...Scope Validation
- If your app requests a scope it hasn't registered, the authorization will fail with
invalid_scope - If a user's role within their organization doesn't have access to certain resources, API calls may return
403even with the correct scope - Scopes cannot be escalated after installation — the user must re-authorize to grant additional scopes
Best Practices
- Request minimum scopes — Only ask for what your app actually needs. Users are more likely to install apps with fewer permission requests.
- Explain why — Use your app description to explain why each scope is needed.
- Separate read and write — If your app only needs to read data, don't request write scopes.
- Add scopes incrementally — Start with minimal scopes and request more as your app's functionality grows. Users can re-authorize to grant additional scopes.
- Handle scope errors — If an API call returns
403, check that your token has the required scope before assuming a bug.