Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.lofty.com/llms.txt

Use this file to discover all available pages before exploring further.

OAuth 2.0 is the recommended authentication method for multi-tenant integrations. Lofty supports three grant types:
Grant TypeUse Case
Authorization CodeWeb apps where a user authorizes access via browser
Authorization Code + PKCESPAs and native apps (no client secret required)
Client CredentialsServer-to-server / CLI (requires customer_key)

​
Prerequisites

You need a Developer Platform account and a registered application. Sign up at the Lofty Developer Portal.

​
Authorization Code flow

1

Register your application

Create a new application in the Developer Portal. Provide your app name, description, and redirect URI(s).New applications start in Development Mode — you can test the full OAuth flow without review.
2

Obtain credentials

After registration, you’ll receive a Client ID and Client Secret.
Never expose your Client Secret in client-side code, public repositories, or logs.
3

Request an access token

Exchange your credentials for an access token via the OAuth 2.0 authorization code flow.
curl -X POST https://api.lofty.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>" \
  -d "code=<AUTHORIZATION_CODE>" \
  -d "redirect_uri=<REDIRECT_URI>"
For complete token endpoint details, see the OAuth 2.0 API Reference.
4

Authenticate requests

Pass the access token in the Authorization header:
curl https://api.lofty.com/v1.0/leads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

​
PKCE flow

For SPAs and native apps that cannot securely store a client secret. Uses a code verifier/challenge instead. 
curl -X POST https://api.lofty.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<CLIENT_ID>" \
  -d "code=<AUTHORIZATION_CODE>" \
  -d "code_verifier=<CODE_VERIFIER>" \
  -d "redirect_uri=<REDIRECT_URI>"
No client_secret is required. The Lofty CLI uses this flow for interactive browser login (lofty-cli auth login-browser).

​
Client Credentials flow

For server-to-server integrations with no user interaction. Requires a customer_key (API key) to identify the target account. 
curl -X POST https://api.lofty.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>" \
  -d "customer_key=<CUSTOMER_KEY>"
The customer_key is the target user’s API key (found in Settings → Integrations → API). The resulting token is scoped to that user’s data and permissions. See CLI Authentication for details.

​
Permission scopes

Each token is scoped to the endpoints granted to your application in the Developer Portal. Calling an out-of-scope endpoint returns HTTP 403: 
{
  "code": 200100,
  "message": "Sorry, the vendor does not have permission for this API."
}
Adding scopes is a breaking change. When you add new permission scopes to a production app, all existing tokens are invalidated (authorized_api_ids changes). Existing users must re-authorize your app. Always notify users before adding scopes.

​
Rate limits by app mode

ModeRate Limit
Development100 requests/min
Production500 requests/min
Rate limits are per-app, not per-account. Set on app_info.rate_limit_per_minute.

​
App lifecycle

StageDescription
DevelopmentTest the full OAuth flow without review. Rate limit: 100/min.
Under ReviewSubmitted for production access.
ProductionApproved. Real users can authorize your app. Rate limit: 500/min.
DeclinedNot approved. Edit and resubmit at any time.

​
Updating a production app

Once in production, edits require review before taking effect. Your app continues operating with the current approved configuration during review. Non-breaking changes — app name, description, redirect URIs, removing scopes. Existing connections are unaffected. Breaking changes — adding new permission scopes invalidates existing tokens. Users must re-authorize. Notify users before submitting.
No. Edit controls are locked during review. Cancel the pending edit first if you need to make urgent changes.
Your app continues operating with its current configuration. You’ll receive the decline reason via email and can resubmit after making adjustments.