Overview

How to build an application for SoftLedger customers: the three integration strategies, the flows behind partner apps, and the review process to become a trusted partner listed on the SoftLedger Marketplace.

Which approach to use

There are three ways to build against SoftLedger. Pick by two questions: whose accounting data does your app touch, and who signs in. See the options below, and the subsequent table to advise which build type is right for you.

Direct API Key
Partner app: account linking
Partner app: Sign in with SoftLedger

	Direct API key	Partner app: account linking	Partner app: Sign in with SoftLedger
Best for	Internal tools, scripts, prototypes, and testing against your own books	A product that reads or writes accounting data for many SoftLedger customers	A product whose users log in with their SoftLedger identity
Whose data	Your own tenant only	Every customer who connects their tenant to your app	The signed-in user's tenant, acting as that user
Credentials	An API key you create in your own tenant	Partner keys issued by SoftLedger	Partner keys issued by SoftLedger
Customer action	None	One-time consent to connect their tenant	Click "Sign in with SoftLedger"
SoftLedger review	No	Yes, before the app is enabled for customers	Yes, when partner keys are issued
Marketplace	Not listed	Listed	Listed

Note: Most partners start with approach 1 to explore the API, then move to approach 2 once they need to serve customers other than themselves. Approach 3 is for apps that want SoftLedger to be the login, and it is often paired with approach 2 so the app can also call the API in the background.

Strategy 1: Direct API key

Use this when the only books your app touches are your own, or to prototype before requesting partner keys. Create a key under Admin > Api Keys, exchange it for a token with the client_credentials grant, and send the token as a Bearer header. Endpoints, scopes, rate limits, and webhooks are all covered in the API docs.

A key belongs to one tenant. Never ask customers to create keys and send them to you; that is what partner apps are for.

Strategy 2: Partner app with account linking

Use this when your product keeps its own login and needs to read or write accounting data in your customers' SoftLedger tenants. Each customer connects once, and you call the API on their behalf with a token you refresh in the background.

SoftLedger issues you an authorization domain, a client_id, and a client_secret. Both partner strategies use the same client.

Resolve endpoints from {authorization domain}/.well-known/openid-configuration.
Run an authorization code flow with PKCE and the scopes openid offline_access. The offline_access scope is what returns a refresh token.
Verify the access token against the JWKS with the issuer pinned. Store the access token, refresh token, and expiry server-side and encrypted, keyed to your own user. The org_id claim is the tenant.
Call the API with Authorization: Bearer <access_token>. Refresh near expiry; refresh tokens rotate, so persist the newest one. A failed refresh means the user must reconnect.

Strategy 3: Sign in with SoftLedger

Use this when SoftLedger should be the login for your app. It uses the same client as Strategy 2; the difference is what you do with the tokens.

Authorize with the scopes openid profile email, adding offline_access if sessions should outlive the access token.
Validate the id_token against the JWKS with the issuer pinned and the audience equal to your client_id, then create your own session from its claims. sub is the stable user id and org_id is the tenant.
Keep the tokens server-side. While the user is signed in, the access token works as a Bearer credential to the API under the same install and permission checks as Strategy 2.

Any SoftLedger user can sign in once your client exists, but API calls succeed only when the user's tenant has installed your app. Handle that login-only state with a prompt to install from Integrations.

	Account linking	Sign in with SoftLedger
Who runs the login	You	SoftLedger
Scopes requested	`openid offline_access`	`openid profile email`, plus `offline_access` for long sessions
What you keep	Access and refresh token tied to your own user	`id_token` claims as your session user, plus the tokens
API access while the user is away	Yes, through the refresh token	Only if you request `offline_access` and persist the refresh token

Request offline_access and persist the refresh token, and one session covers both interactive requests and background sync.

Becoming a partner

Partner keys are issued by SoftLedger rather than self-serve. Email support@softledger.com with the details below and expect a short review before your app is enabled for customers.

What to send

Item	Notes
App name and description	Shown to customers on the Integrations page
Icon URL	Square image served over HTTPS
Launch URL	Where the SoftLedger sidebar link opens your app
Redirect URIs	Exact HTTPS callback URLs, one per environment. Localhost URIs are fine for development
Scopes	Least privilege. Same vocabulary as API keys, for example `list:Invoices` or `create:JournalEntry`. The full list is in the API reference
Test tenants	Your own SoftLedger tenants, so they can be whitelisted for development
Expected volume	Requests per minute per customer, if you expect to exceed 200
Technical and security contact	For incidents, secret rotation, and review questions

What happens next

SoftLedger creates your OAuth client and returns the authorization domain, client_id, and client_secret. Your app is registered inactive and visible only to whitelisted tenants.
Your own tenants are whitelisted so you can install, connect, and test end to end.
Review. SoftLedger checks the scopes you requested against what the app does, confirms the client secret and tokens stay server-side, confirms redirect URIs are HTTPS, and walks through install, connect, disconnect, and uninstall.
Pilot. The app is activated and a few named customer tenants are whitelisted.
Listing. Visibility opens to all tenants and your app appears under Trusted Partner Apps.

Questions about getting started as a softledger partner? Reach out through the chat bubble or at support@softledger.com — happy to help.

Building on SoftLedger: Integration Strategies