Laserfiche Cloud offers two ways to connect Caddi: a user OAuth 2.0 client, where each person authorizes their own account, and a Service Principal, where Caddi acts as a single non-human account. This guide covers the Service Principal route — the right choice when you want one consistent identity and no per-user sign-in.
Service Principal authentication is Laserfiche Cloud only and uses a client-credentials flow. There is no user sign-in step, so https://app.trycaddi.com/oauth-callback is not used here. For Laserfiche Self-Hosted, or for per-user connections, use the Laserfiche OAuth 2.0 client setup instead.
Before you start
You'll need:
Laserfiche Cloud (this flow does not exist for Self-Hosted)
The Developer Console Administrator role, to open the Developer Console
The Trustee Administration role, to create Service apps
Owner or Admin access to your Caddi organization
To know which Laserfiche data center your account is in — the Developer Console URL you sign in to tells you (
app.laserfiche.com,app.laserfiche.ca, orapp.eu.laserfiche.com)
Step 1: Create the Service Principal
A Service Principal is a licensed non-human trustee. Its repository rights define the ceiling on what Caddi can do, so grant ordinary user-level rights rather than administrator rights.
A Service Principal can hold two active keys at once, which lets you rotate without downtime. The Rotate action regenerates a key.
In Laserfiche Cloud, open the app switcher in the top right and choose Account to reach Account Administration.
Go to the Users tab, then the Service Principals sub-tab.
Click Add Service Principal.
Set the username, display name, and group membership.
Grant the repository access rights your loops need on the target repository.
Save, then choose Create Service Principal Key(s) on the new principal.
Copy the key immediately — Laserfiche displays it only once.
Step 2: Create the Service app in the Developer Console
The Service Principal alone isn't enough — it has to be paired with an OAuth Service app.
Open the Developer Console for your data center, for example app.laserfiche.com/devconsole.
Click New → Create Application and choose the app type Service.
Name it
Caddiand click Create Application.On the App Configuration page, under the Service Account section, select the Service Principal you created in Step 1.
Open the Authentication tab, enter your OAuth 2.0 Scopes (see below), and click Update Scopes.
Still on the Authentication tab, create an Authorization Key: paste in a valid Service Principal key and Laserfiche returns a long-lived authorization key.
Copy or download the key — it is shown only once. A Service app can hold a maximum of two access keys.
Scopes are case-sensitive and space-delimited. For repository read and write, enter repository.Read repository.Write. The combined form repository.ReadWrite is also accepted.
Step 3: Configure Laserfiche in Caddi
This step must be completed by a Caddi organization owner or admin.
In Caddi, open Integrations in the left sidebar, then click the Integration Setup tab at the top of the page. This tab is only visible to organization owners and admins.
Find Laserfiche - Custom Service Principal in the list and click Configure.
Enter the following values:
Service Principal Key — the Authorization Key generated in Step 2. Despite the field label, this is the authorization key value, not the raw Service Principal key.
Scope (Optional) — leave blank to inherit the scopes configured on the Service app, or enter a space-separated subset such as
repository.Read repository.Write.
Click Save Configuration. Caddi validates the credentials immediately — if something is wrong you'll see an error right away, and nothing is stored until validation passes.
How the connection behaves
One shared identity. Every Caddi user acting on Laserfiche does so as the Service Principal. All repository actions are audited under the Service Principal's name, not the end user's — worth knowing if your compliance team reviews those logs.
Effective access is the intersection of the scopes on the Service app and the Service Principal's own repository rights. Both have to allow an action.
Service Principal keys expire after 90 days by default, and an Authorization Key is invalidated when its underlying Service Principal key expires or is rotated. This is the most common reason a working Laserfiche integration goes quiet. You can change the expiry at Account Administration → Settings → Integration Configuration, or put a rotation reminder on the calendar.
Access tokens last 12 hours and no refresh token is issued for service apps. Caddi re-requests a token as needed; nothing to manage on your side.
Revoking access. Delete the Authorization Key, rotate the Service Principal key, or disable the Service Principal.
Troubleshooting
unauthorized_client when saving
The Developer Console app is not of type Service, or no Service Principal is assigned to it. Check the Service Account section on the App Configuration page.
The integration worked for about three months and then stopped
The Service Principal key hit its 90-day expiry, which invalidated the Authorization Key. Rotate the Service Principal key, generate a new Authorization Key, and update Caddi. Consider extending the expiry under Integration Configuration.
Caddi can read documents but not write them
Either the Service app's scopes are read-only, or the Service Principal lacks write rights on the repository. Both have to allow it — check the Authentication tab first, then the principal's repository rights.
Scope errors despite entering the right scopes
Laserfiche scopes are case-sensitive. repository.read will fail where repository.Read succeeds.
Still stuck? Contact Caddi support with the exact error message you're seeing and the time it occurred.
Automation ideas
Law Firms
Signed document → repository filing
Caddi files executed documents into the right Laserfiche folder with the metadata your retention policy expects, and logs the activity against the matter.
Records request → assembled response
Caddi searches the repository, assembles responsive documents, and produces the index — turning a half-day of clicking into a review step.
RIAs
Client document → indexed and filed
Caddi reads incoming statements and agreements, extracts the client and account identifiers, and files them to Laserfiche with the correct metadata for compliance retrieval.
Compliance review → evidence pack
Caddi pulls the documents an examiner has asked for and assembles them into a single reviewed pack, with a log of what was included.