Authentication

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.

Method	Best for	Configured via
Token URL	CI/CD, automation with session ID	`LOFTY_TOKEN_URL` + `LOFTY_SESSION_ID`
Browser OAuth (PKCE)	Interactive developer use	`lofty-cli auth login-browser`
Client Credentials	Server-to-server	`LOFTY_CLIENT_ID` + `LOFTY_CLIENT_SECRET` + `LOFTY_CUSTOMER_KEY`
Direct Token	One-off testing, CI injection	`LOFTY_ACCESS_TOKEN`

Tokens obtained by Token URL, Browser OAuth, and Client Credentials are cached locally and refreshed automatically when they expire.

Token URL (highest priority)

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)

The simplest method for interactive use. The CLI launches your default browser, you log in once, and the token is stored locally.

lofty-cli auth login-browser

The flow uses OAuth 2.0 with PKCE — no client secret is needed on your machine.

OAuth client credentials

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.

Configure client credentials

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

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"

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.

Direct access token

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

Command	Purpose
`lofty-cli auth status`	Show which method resolved and where credentials came from
`lofty-cli auth test`	Make a real API call (typically `GET /me`) to confirm the token works
`lofty-cli auth show`	Print 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

Path	Created by	Contents
`~/.config/lofty-cli/customer-key`	`auth set`	Plain-text customer key (chmod 600)
`~/.config/tokens/lofty-session-cache.json`	`auth login-session`	Token URL response
`~/.config/tokens/lofty-pkce-cache.json`	`auth login-browser`	Browser OAuth tokens
`~/.config/tokens/lofty-oauth-cache.json`	`auth login`	Client-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).

Get Started

Core Concepts

Guides

Lofty CLI

Authentication

Verifying authentication

Logging out

Where credentials live on disk

Troubleshooting

​Verifying authentication

​Logging out

​Where credentials live on disk

​Troubleshooting

Verifying authentication

Logging out

Where credentials live on disk

Troubleshooting