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:
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, orreadandwrite.
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#
| Scope | Can call | A write with it answers |
|---|---|---|
read | every GET, and POST /mcp for read tools | 403 api_key_read_only |
read + write | everything on the public API | as 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.
Every group-scoped call still runs the same guards as the app:
- A group you are not in answers
404 not_found, never403, 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 reach | Why |
|---|---|
| Your profile, sign-in methods, phone and photo | They 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 account | Irreversible, so never delegated. |
| Invite links, personal links, people codes, quick-split links | They 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 notifications | Push tokens and notification settings belong to your phones. |
| Writing off a debt | Forgiving money is a decision for a person at a screen. Reading write-offs is allowed. |
| The keys themselves | A 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
.envto.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. Keepwritefor the automations that add things.
If a key leaks#
- Open Me › Profile › Developer and choose Regenerate. The leaked secret stops working immediately.
- Check the request log (below) for calls you do not recognise.
- 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#
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthenticated | No Authorization: Bearer … header. |
| 401 | api_key_invalid | Not a key we know: mistyped, regenerated or deleted. |
| 401 | api_key_disabled | The key is switched off in the app. |
| 403 | api_key_not_allowed | The route is not on the public API. |
| 403 | api_key_read_only | A write with a read-only key. |
| 429 | rate_limited | Too many requests; see Rate limits. |
The full list is on Errors.