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.

lofty-cli supports four authentication methods. They are evaluated in priority order at every command invocation: the first one that yields a valid access token wins. Pick the method that fits how you are running the CLI.
MethodBest forConfigured via
Token URLCI/CD, automation with session IDLOFTY_TOKEN_URL + LOFTY_SESSION_ID
Browser OAuth (PKCE)Interactive developer uselofty-cli auth login-browser
Client CredentialsServer-to-serverLOFTY_CLIENT_ID + LOFTY_CLIENT_SECRET + LOFTY_CUSTOMER_KEY
Direct TokenOne-off testing, CI injectionLOFTY_ACCESS_TOKEN
Tokens obtained by Token URL, Browser OAuth, and Client Credentials are cached locally and refreshed automatically when they expire.
Use this when an upstream system can mint a session ID and exchange it for tokens through a custom endpoint.
export LOFTY_TOKEN_URL="https://your-auth-server.example.com/token"
export LOFTY_SESSION_ID="ses_xxx"
lofty-cli auth login-session
You can also pass the values inline:
lofty-cli auth login-session --tokenurl https://... --sessionid ses_xxx
Tokens are cached at ~/.config/tokens/lofty-session-cache.json and refreshed transparently.

Browser OAuth (recommended for humans)

Use this for server-to-server scenarios where there is no human to complete a browser flow. Implements the OAuth 2.0 Client Credentials Grant with an additional resource owner identifier.
1

Register an OAuth application

Sign in to the Lofty Developer Portal to create an application and obtain your client_id and client_secret.
2

Configure client credentials

export LOFTY_CLIENT_ID="your-client-id"
export LOFTY_CLIENT_SECRET="your-client-secret"
3

Specify the target account

The customer key identifies which Lofty account’s data the CLI will access (the resource owner). Each Lofty user has a unique API key — find it in the Lofty CRM under Settings > Integrations > API.
export LOFTY_CUSTOMER_KEY="your-customer-key"
4

Exchange for an access token

lofty-cli auth login
Unlike a standard Client Credentials Grant where the client acts on its own behalf, Lofty requires LOFTY_CUSTOMER_KEY to specify which account to access. The token is scoped to that account’s data and permissions.
When another system has already obtained an access token (e.g. a CI job that ran auth login upstream), inject it directly:
export LOFTY_ACCESS_TOKEN="eyJhbGciOi..."
export LOFTY_REFRESH_TOKEN="dGhpcyBpcyBh..."   # optional
No auth login* command is required; the token is used as-is.

​
Verifying authentication

CommandPurpose
lofty-cli auth statusShow which method resolved and where credentials came from
lofty-cli auth testMake a real API call (typically GET /me) to confirm the token works
lofty-cli auth showPrint the active customer key (masked by default)

​
Logging out

lofty-cli auth logout
This deletes the Token URL cache, the PKCE token, the OAuth refresh cache, and the saved customer key. It does not revoke server-side sessions — for that, rotate the credential at its source.

​
Where credentials live on disk

PathCreated byContents
~/.config/lofty-cli/customer-keyauth setPlain-text customer key (chmod 600)
~/.config/tokens/lofty-session-cache.jsonauth login-sessionToken URL response
~/.config/tokens/lofty-pkce-cache.jsonauth login-browserBrowser OAuth tokens
~/.config/tokens/lofty-oauth-cache.jsonauth loginClient-credentials tokens
Never commit any of these files to source control. Use auth logout or remove the directory to wipe state.

​
Troubleshooting

If auth test fails, see Troubleshooting for the common causes (clock skew, expired refresh token, wrong customer key, missing scope).