Skip to main content
The v2 API has no API keys. Your integration signs in with the username and password of a LedgerSync login, gets back a token, and sends that token in an Auth-Token header on every other call. A token lasts 30 minutes.
Sandbox: https://staging.ledgersyncappv2.com. Production: https://ledgersyncappv2.com. Each environment has its own logins, so sign in to each with a login created there. Building on v3 instead? It uses API keys; see Authentication.

Sign in

POST /api/v2/public/authenticate with the login’s username and password:
The old v2 reference also listed fromApi, ipAddress and userAgent in the request. Leave them out. fromApi already defaults to true, the value for API sign-ins; set to false, the sign-in follows the web app’s rules instead and can be refused or come back without a token. LedgerSync ignores ipAddress and userAgent and reads both from your request.
To keep the token in a shell variable for the calls that follow:

Sign in with an email address

POST /api/v2/public/authenticate-by-email takes the login’s email address instead of its username:
The response has the same fields as above, and its username tells you the login’s username. It works when exactly one LedgerSync login has that email address. When more than one does, it answers 403 with This email is linked to more than one account. Please sign in with your username, or contact support. Sign in with the username instead.

Send the token

Put the authToken value in an Auth-Token header on every call outside /api/v2/public/:
v2 reads only the Auth-Token header. An Authorization: Bearer ... header, the v3 style, is not read, and the call answers 401 with User not authorized to perform request!. Keep the Bearer at the start of the token too: without it the call answers 401 with Token has expired!.
Calls under /api/v2/public/, such as sign-in and password reset, do not check the header.

How long a token lasts

A token works for 30 minutes from sign-in, and using it does not extend that time. Sign in again before the 30 minutes are up, or as soon as a call answers 401, and carry on with the new token. Signing in again does not end earlier tokens. Several jobs can sign in with the same login at the same time, and each token runs out on its own.

Log out

POST /api/v2/public/logout with the token in the Auth-Token header ends it before its 30 minutes are up:
It answers 204 No Content, whatever the token, even one that has already expired. From then on the API answers 401 with User not authorized to perform request! to that token. Logging out is optional: a token also runs out by itself.
The logout request has no body, but it still needs a Content-Length header: a POST without one is refused with 411 Length Required. curl sends none for a bare -X POST, hence the -H "Content-Length: 0".

Errors

When signing in

A refused sign-in comes back in the same shape as a successful one:
403 Forbidden
A 400 has a different body:
400 Bad Request
A few other refusals, for example a login whose LedgerSync setup is not complete, come back with another 4xx status (412, 417 or 426) and a message. Send that message to LedgerSync support.

On every other call

Both bodies are plain text, not JSON. On either one, sign in again and retry with the new token.

Keep the login safe

Your integration holds a real LedgerSync login. Three wrong passwords in a row, each less than five minutes after the one before, lock that login, in the LedgerSync web app as well as here. It then stays locked, even for the right password, until it is unlocked. Do not retry a refused sign-in in a loop.Resetting the password unlocks it: POST /api/v2/public/password/reset with the login’s username in the body emails a reset link to the login’s email address, and setting a new password through that link unlocks the login. A client or employee login can also be unlocked by its firm, with PATCH /api/v2/client/unlock/{username} or PATCH /api/v2/employee/unlock/{username}.
Treat the password and the token like any other credential: keep them on your server, never in a browser or a mobile app.