OAuth 2.0

OAuth 2.0 is the recommended authentication method for multi-tenant integrations. Lofty supports three grant types:

Grant Type	Use Case
Authorization Code	Web apps where a user authorizes access via browser
Authorization Code + PKCE	SPAs and native apps (no client secret required)
Client Credentials	Server-to-server, using an API Key the account holder gives you

The first two are served by https://crm.lofty.com/api/user-web/oauth/token; Client Credentials is served by https://api.lofty.com/oauth/token. They differ in more than the host — see Choosing between them.

Prerequisites

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

Authorization Code flow

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.

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.

Request an access token

Exchange your credentials for an access token via the OAuth 2.0 authorization code flow.

curl -X POST https://crm.lofty.com/api/user-web/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic <BASE64_OF_CLIENT_ID:CLIENT_SECRET>" \
  -d "grant_type=authorization_code" \
  -d "code=<AUTHORIZATION_CODE>" \
  -d "client_id=<CLIENT_ID>" \
  -d "redirect_uri=<REDIRECT_URI>"

The Authorization header uses HTTP Basic authentication: Base64-encode <CLIENT_ID>:<CLIENT_SECRET> to produce the credential string.For complete token endpoint details, see the OAuth 2.0 API Reference.

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://crm.lofty.com/api/user-web/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 where there is no browser to send a user to. Instead of a user approving your app, the account holder creates an API Key in their Lofty CRM (Settings → Integrations → API Keys) and gives it to you. You exchange it, together with your app credentials, for a short-lived access token.

This endpoint is not the one the other two flows use. Different host, JSON body instead of form fields, and credentials in the body instead of an Authorization header. Sending one flow’s request shape to the other endpoint fails with a message that does not point at the mismatch.

curl -X POST https://api.lofty.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
        "grant_type": "client_credentials",
        "client_id": "<CLIENT_ID>",
        "client_secret": "<CLIENT_SECRET>",
        "customer_key": "<API_KEY>"
      }'

Field	Notes
`grant_type`	Fixed value `client_credentials`.
`client_id`, `client_secret`	Your app’s credentials, from the Developer Portal. In the body, not an `Authorization` header.
`customer_key`	The account holder’s API Key. Omitting it returns `Missing required parameter: api_key`.
`scope`	Optional, defaults to `openapi`.

A successful response:

{
  "scope": "openapi",
  "access_token": "oat_eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "user_id": 123456789012345,
  "refresh_token": null,
  "refresh_expires_in": 0
}

The token is prefixed oat_, lasts 2 hours, and carries no refresh token — mint a new one when it expires. Send it as Authorization: Bearer <ACCESS_TOKEN>, the same as any other access token.

The token’s scope comes from the API Key, not from your app. An exchanged token can reach exactly the endpoints the account holder selected when creating their key. Permissions your app is registered for but the key does not carry are refused; permissions the key carries are reachable whether or not your app lists them.So an integration can be configured correctly on the Developer Portal and still get 403 on every call, simply because the key it was given is narrower. When a call is refused, check the key’s permissions first.

Choosing between them

	Authorization Code (+ PKCE)	Client Credentials
Endpoint	`https://crm.lofty.com/api/user-web/oauth/token`	`https://api.lofty.com/oauth/token`
Body	`application/x-www-form-urlencoded`	`application/json`
Client authentication	HTTP Basic header and `client_id` in the body (PKCE: `code_verifier`, no secret)	`client_id` + `client_secret` in the body
User interaction	Browser consent screen	None — the account holder hands over an API Key
Token shape	Opaque UUID	Prefixed `oat_`
Access token lifetime	10 days (`expires_in: 864000`)	2 hours (`expires_in: 7200`)
Refresh token	Yes	No
Scope comes from	The permissions your app requested and the user approved	The API Key’s permissions
`403` error code	`200100`	`200127`

Permission scopes

Calling an endpoint a token is not scoped for returns HTTP 403. The body differs by grant type, because the two are checked against different records:

// Authorization Code — checked against the permissions the user approved for your app
{
  "code": 200100,
  "message": "Sorry, the vendor does not have permission for this API."
}

// Client Credentials — checked against the API Key the token was minted from
{
  "code": 200127,
  "message": "This API Key was not granted permission for this endpoint. Create a new API Key that includes it, or use a key that does."
}

Both mean the same thing — the call is outside the token’s scope — but they point at different places to fix it. See Error codes.

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.

App lifecycle

Stage	Description
Development	Test the full OAuth flow without review. Rate limit: 100/min.
Under Review	Submitted for production access.
Production	Approved. Real users can authorize your app. Rate limit: 500/min.
Declined	Not 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.

Can I edit while a review is pending?

No. Edit controls are locked during review. Cancel the pending edit first if you need to make urgent changes.

What happens if my edit is declined?

Your app continues operating with its current configuration. You’ll receive the decline reason via email and can resubmit after making adjustments.

Get Started

Authentication

Core Concepts

Guides

Lofty CLI

Prerequisites

Authorization Code flow

PKCE flow

Client Credentials flow

Choosing between them

Permission scopes

App lifecycle

Updating a production app

​Prerequisites

​Authorization Code flow

​PKCE flow

​Client Credentials flow

​Choosing between them

​Permission scopes

​App lifecycle

​Updating a production app

Prerequisites

Authorization Code flow

PKCE flow

Client Credentials flow

Choosing between them

Permission scopes

App lifecycle

Updating a production app