dimesumdevelopers API reference Console Open the app

Authentication and keys

One key per account, made in the app, sent as a bearer token. It acts as you: every membership check, read-only rule and editor policy that applies to you in the app applies to the key.

Sending the key#

Every request carries the key in the Authorization header:

HTTP
Authorization: Bearer dms_live_4hX2...

Keys start with dms_live_. The prefix is there so secret scanners (GitHub's, your CI's, gitleaks) recognise a Dimesum key the moment one lands somewhere it should not. The key's first few characters (for example dms_live_Ab3x) are its prefix, shown in the app and by GET /v1/developer/key so you can tell keys apart without seeing the secret.

A request with no header, or a header that is not Bearer …, answers 401 unauthenticated.

Making a key#

Keys are made in the app, under Me › Profile › Developer, while you are signed in. A key can never make, widen or read another key, so a leaked key cannot be used to mint a better one.

When you create it you choose:

  • A name, up to 60 characters, so you remember what it is for.
  • A scope: read, or read and write.

The key is shown once, at creation. Dimesum keeps only its SHA-256 hash, which is enough to recognise the key when you send it and useless to anyone who reads the database.

Scopes#

ScopeCan callA write with it answers
readevery GET, and POST /mcp for read tools403 api_key_read_only
read + writeeverything on the public APIas normal

write always comes with read. Each operation in the reference names the scope it needs. Over MCP, POST /mcp itself is allowed with a read key, and each tool's own REST calls are held to the key's scope, so a write tool called with a read-only key comes back as a tool error carrying api_key_read_only.

One key per account#

An account has at most one live key. To change its scope, or to hand a fresh secret to a new machine, you regenerate or delete it and make another. One key keeps the question "what can reach my account" answerable at a glance, and the request log below covers all of it.

Switching a key off and on#

In Me › Profile › Developer a key can be switched off without losing it. While it is off, every call answers 401 api_key_disabled; switch it back on and the same secret works again. Use this when you are not sure whether something is misbehaving and want it to stop now.

Regenerating#

Regenerate issues a new secret for the same key (same name, same scopes) and the old secret stops working at once. Update the places that use it: the next request with the old one answers 401 api_key_invalid.

Deleting#

Delete removes the key entirely. Anything using it gets 401 api_key_invalid from the next request. You can make a new key afterwards.

Switching, regenerating and deleting are done in the app with a signed-in session, never with a key.

What a key can reach#

The public API is an allowlist. A key may call these operations and nothing else; a key on any other route answers 403 api_key_not_allowed.

MethodPathWhat it doesScope
GET/v1/meWho you areread
GET/v1/me/balancesBalances across every groupread
GET/v1/me/activityYour activity feedread
GET/v1/me/insightsYour spending insightsread
GET/v1/peoplePeople you keepread
GET/v1/groupsList groupsread
POST/v1/groupsCreate a groupwrite
GET/v1/groups/{groupID}Get a groupread
POST/v1/groups/{groupID}/membersAdd a kept placewrite
GET/v1/groups/{groupID}/balancesGroup balancesread
GET/v1/groups/{groupID}/activityA group's activity feedread
GET/v1/groups/{groupID}/insightsGroup insightsread
GET/v1/groups/{groupID}/editorsWho can edit billsread
GET/v1/groups/{groupID}/expensesList billsread
POST/v1/groups/{groupID}/expensesAdd a billwrite
GET/v1/groups/{groupID}/expenses/{expenseID}Get a billread
PATCH/v1/groups/{groupID}/expenses/{expenseID}Edit a billwrite
DELETE/v1/groups/{groupID}/expenses/{expenseID}Delete a billwrite
GET/v1/groups/{groupID}/expenses/{expenseID}/revisionsA bill's historyread
GET/v1/groups/{groupID}/expenses/{expenseID}/commentsA bill's commentsread
POST/v1/groups/{groupID}/expenses/{expenseID}/commentsComment on a billwrite
PUT/v1/groups/{groupID}/expenses/{expenseID}/fx-rateSet a bill's ratewrite
GET/v1/groups/{groupID}/recurringRepeatsread
POST/v1/groups/{groupID}/recurringCreate a repeatwrite
GET/v1/groups/{groupID}/settlementsPaymentsread
POST/v1/groups/{groupID}/settlementsRecord a paymentwrite
POST/v1/groups/{groupID}/settlements/{settlementID}/confirmConfirm a paymentwrite
POST/v1/groups/{groupID}/settlements/{settlementID}/disputeDispute a paymentwrite
GET/v1/settlement-batches/{batchID}One payment across groupsread
POST/v1/settlement-batches/{batchID}/confirmConfirm a payment across groupswrite
POST/v1/settlement-batches/{batchID}/disputeDispute a payment across groupswrite
GET/v1/groups/{groupID}/write-offsForgiven debtsread
POST/v1/capturesRead a line into a draftwrite
GET/v1/suggestionsSuggestionsread
GET/v1/suggestions/{suggestionID}A suggestionread
POST/v1/suggestions/{suggestionID}/confirmConfirm a suggestionwrite
POST/v1/suggestions/{suggestionID}/dismissDismiss a suggestionwrite
GET/v1/fx/quoteA market rateread
GET/v1/developer/keyThis keyread
POST/mcpMCP endpointread

Every group-scoped call still runs the same guards as the app:

  • A group you are not in answers 404 not_found, never 403, so a key cannot even learn that a group exists.
  • A read-only group refuses writes with 403 read_only.
  • Changing somebody else's bill follows the group's editor policy (403 not_editor).

What a key cannot reach, and why#

Out of reachWhy
Your profile, sign-in methods, phone and photoThey decide who can get into your account. Changing them is for you, at a screen.
Payment details (the ways people pay you)They are where money goes. A script that could change them could redirect a payment.
Deleting the accountIrreversible, so never delegated.
Invite links, personal links, people codes, quick-split linksThey are capabilities: anyone holding one can join or claim. Minting them from a script would hand out access.
Claims (taking over a kept place)Joining somebody's history is a decision for the person joining.
Devices and notificationsPush tokens and notification settings belong to your phones.
Writing off a debtForgiving money is a decision for a person at a screen. Reading write-offs is allowed.
The keys themselvesA key can never mint, widen or read a key.

Keeping the key secret#

A key is as good as your password for everything in the table above, so treat it that way:

  • Read it from the environment (DIMESUM_API_KEY) or your platform's secret store: Apps Script's Script Properties, n8n or Zapier credentials, a CI secret, the macOS Keychain.
  • Never put it in client-side code you ship: a web page, a mobile app bundle or a browser extension gives it to everyone who opens it. The API only accepts browser calls from this site's console, and the console never stores it.
  • Never commit it. Add your .env to .gitignore. If one slips into a commit, treat it as leaked even if you delete the commit.
  • Use the narrowest scope. A dashboard needs read. Keep write for the automations that add things.

If a key leaks#

  1. Open Me › Profile › Developer and choose Regenerate. The leaked secret stops working immediately.
  2. Check the request log (below) for calls you do not recognise.
  3. Put the new secret where it belongs.

If you only suspect a leak, switching the key off stops everything at once while you look.

The request log#

Every request a key makes is logged for its owner: when, the method, the path (with any capability token in it masked), the status and how long it took. The app shows the last 100 under Me › Profile › Developer, and the key itself can read its last 50, with its scopes and rate limit, from GET /v1/developer/key. The console shows the same.

Errors you will see here#

StatusCodeMeaning
401unauthenticatedNo Authorization: Bearer … header.
401api_key_invalidNot a key we know: mistyped, regenerated or deleted.
401api_key_disabledThe key is switched off in the app.
403api_key_not_allowedThe route is not on the public API.
403api_key_read_onlyA write with a read-only key.
429rate_limitedToo many requests; see Rate limits.

The full list is on Errors.