Overview

All API requests require authentication via the Authorization header.

Method	Header format	Best for
OAuth 2.0	`Bearer <access_token>`	Multi-tenant apps, third-party integrations
API Key	`token <api_key>`	Personal automation, scripts, CLI

Which method should I use?

Scenario	Method	Grant Type
CLI tool (`lofty-cli`)	API Key	Used as `LOFTY_CUSTOMER_KEY` in Client Credentials
Personal scripts / automation	API Key	Direct `token` header
Server-to-server (no user)	OAuth 2.0	Client Credentials + `customer_key`
Web app (user authorizes)	OAuth 2.0	Authorization Code
SPA / mobile app	OAuth 2.0	Authorization Code + PKCE
Multi-tenant SaaS platform	OAuth 2.0	Authorization Code

Three grant types: Authorization Code, PKCE, and Client Credentials. Scoped permissions with security review.

User-scoped personal access tokens. Configurable expiration and THIRD_PARTY_OPERATION scope.

https://api.lofty.com

curl https://api.lofty.com/v1.0/leads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>"

Or via CLI:

lofty-cli leads list --limit 10

Rate limits are per-app (not per-account), configured on each registered application.

App Mode	Rate Limit
Development	100 requests/min
Production	500 requests/min

The window resets every 60 seconds. Every response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Time (UTC epoch seconds) when the window resets

When the limit is exceeded, the API returns HTTP 429:

HTTP/1.1 429
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 21000
{"message":"Too Many Requests"}

Some endpoints (e.g. AI features) have lower per-endpoint limits. Check the X-RateLimit-Limit header in responses to determine the actual limit.

HTTP Status	Code	Description
`401`	—	Invalid or missing authentication credentials.
`403`	`200100`	Token is valid but lacks the required permission scope. Grant the scope in the Developer Portal and re-authorize.
`429`	—	Rate limit exceeded. Retry with backoff.

See Error Codes for the full reference.