API keys

Everything that connects to MoneyLights from outside the app — a script, an integration, an AI assistant — authenticates with an API key. One credential type, one place to manage it, one revoke button.

Creating a key

Go to Settings → API keys as an Owner or Admin of your organization. A Member can edit data in the app but cannot issue a key: a key acts unattended, which is a different kind of responsibility.

When you create a key you choose:

• A name — name it after the system that will use it, not the person.
• Scopes — exactly what the key may do (see below).
• An expiry — 30, 90, 180 or 365 days. There is no “never expires” option, on purpose: a credential nobody ever thinks about again is a credential nobody notices has leaked.
• An IP allow-list (optional) — restrict the key to your own infrastructure, so a leaked key is a key that works from nowhere else.

The secret (ml_sk_…) is shown once, at creation. MoneyLights stores only a hash, so nobody — including support — can recover it later. If you lose it, rotate the key.

Give each integration its own key. You can then cut one without taking the others down, and the usage figures tell you which system is doing what.

Scopes

Scopes are resource:action pairs — for example transactions:read or documents:write. A key holds only the scopes you granted it, and:

• Write implies read, never the reverse. vendors:write can also read vendors; vendors:read can never write.
• Scopes cannot be edited after creation. Needing a new scope means creating a new key — widening a credential in place would be a change nobody sees.

What a key can actually do is recalculated on every request:

effective permissions = the key’s scopes ∩ what its creator can do now ∩ your plan

So if the person who created a key is demoted, the key narrows on the very next call. If they leave the organization, their keys stop working immediately. Issue keys under an account that is going to stay.

Rotation

Rotating issues a new secret for the same key and lets you choose how long the old one keeps working: immediately, 24 hours, or 7 days. The window exists so you can deploy the new secret without downtime. The key keeps its name, scopes, IP restrictions and expiry.

Rotate when someone with access to the secret leaves, when it may have been exposed, and on whatever schedule your own policy sets.

Expiry warnings

The key’s creator is notified 14, 7 and 1 day before a key expires, and once it has expired. Those notifications cannot be switched off. Do not wait for the last one: rotating at 14 days costs a deployment; discovering an expired key at zero costs an outage.

Storing the secret

• Use environment variables or a secret manager — never source control, never a config file that ships with your app.
• Never put the key in a URL, a log line or an analytics event. Requests carrying a key in the query string are refused outright.
• Never use a key in client-side code. A key in a browser or a mobile app has been given to everyone who uses it.

Suspect a leak? Revoke first, investigate afterwards. Revocation is in Settings → API keys, takes effect immediately, and is always available — even if your subscription is in arrears.

Next steps

With a key in hand, you can call the REST API or connect an AI assistant over MCP — it is the same credential for both.