A L M A S ALMASHelp Open in the app

29c. API Keys

An API key is a long-lived password-replacement that you can hand to a 3rd-party app, a webhook sender, or an AI agent so it can act on your behalf in ALMAS — without sharing your real password. The key is tied to your account, locked to one of your tenants, and limited to a subset of your permissions. If you ever revoke or rotate it, every integration using it stops working immediately.

Typical uses:

  • Letting a payment provider's webhook (Stripe, PayPal) record transactions in ALMAS.
  • Connecting a bookkeeping tool that reads your invoices nightly.
  • Giving an AI assistant (Claude, a custom GPT) read or write access to your projects, tasks and finances over MCP — see Connecting an AI agent at the end of this section.
  • Wiring up a custom dashboard, a CSV exporter, a Zapier-style automation.

Where to find the page

Open My profile → Security & access → API Keys — or jump straight to /profile/api-keys. The list shows every key you've created, with its name, target tenant, status (active / expired / revoked), expiry, and the date it was last used.

Creating a key

Click New key. A short form asks for:

  • Name — what this key is for, in plain English. Use the name of the system you're connecting (Stripe webhook, Claude assistant on my laptop, Q3 finance export script). A vague name like key1 makes future-you regret choosing it.
  • Tenant — pick one. A key is bound to exactly one tenant for the rest of its life. If you need access to two tenants, create two separate keys.
  • Permissions mode — two choices:
    • Mirror my permissions — the key automatically gets everything you currently have on this tenant, and follows you as your role changes. If you lose delete invoice next month, the key loses it too the next time someone uses it. Best for general-purpose integrations where the access mirrors how you'd act in the UI.
    • Pick specific permissions — tick exactly the abilities you want this key to have, from a checkbox tree of your current permissions. Best for narrow, single-purpose keys (e.g. a webhook that only needs create transaction — even if you later get more powerful, this key stays locked to its narrow scope).
  • Expires in — pick a preset: 30 days, 90 days (default), or 365 days. Every key has an expiry; "never expires" isn't an option.
  • IP allowlist (optional, advanced) — comma-separated IPs or CIDR ranges. If set, the key only works from those addresses. Useful when you know your integration runs on a fixed server (e.g. 54.187.0.0/16 for an AWS region).
  • Rate limit (optional, advanced) — slow the key down on purpose. Defaults to the same 60-requests-per-minute cap that your UI session has; you can lower it but not raise it.

Click Create. A dialog pops up showing the secret — a long string starting with almas_live_. This is the only time the secret is shown. Copy it immediately into wherever your integration stores credentials (a password manager, a secrets vault, your CI/CD's environment variables, etc.). Once you close the dialog, the secret is gone — ALMAS only stores a hashed version and cannot retrieve it again. Lose the secret and you'll have to rotate the key (see below) to get a new one.

Rotating a key

Click Rotate on any active key. ALMAS issues a brand-new secret for the same key (same name, same tenant, same permissions) and keeps the old secret working for a grace window — 24 hours by default, up to 7 days if you pick a longer one on the rotate dialog. During that window, your integration sees two valid secrets: the old one keeps the lights on while you update the integration's config to the new one. When the grace window ends, the old secret stops working automatically. No downtime, no scramble.

Rotate a key when:

  • A vendor leaks credentials (you'll hear about it in their breach notice).
  • Your security policy says "rotate every quarter."
  • An employee with access to your integration's config leaves the company.
  • You lose the original secret and need a fresh copy.

Revoking a key

Click the revoke (red ×) icon next to a key. There's no grace window — the key stops working immediately, every active session using it gets a 401 on the next request. Use revoke as a kill switch: when you suspect a key was leaked, when the vendor you gave it to no longer needs access, when you're decommissioning an integration. Revoked keys stay visible in the list (so you have an audit trail) but they cannot be un-revoked — if you change your mind, create a new key.

What happens when your permissions change

Permissions are intersected on every request — the key never gives more access than you currently have. Two examples:

  • Mirror mode. You're an admin on the Acme tenant. You created a mirror-mode key for a bookkeeping tool. Your role drops to read-only because of a reorganisation. Within seconds, the bookkeeping tool can still read invoices but its next attempt to edit one returns 403. No action needed from you.
  • Specific-permissions mode. You gave a key read invoice + read transaction. You later acquire delete invoice on the same tenant. The key still cannot delete invoices — its abilities are frozen at what you picked at creation. To extend the key you'd have to rotate it (rotation re-validates abilities against your current permissions and lets you add new ones).

Lose access to the tenant entirely (e.g. you're removed from it)? Every key bound to that tenant stops working on the next request. Restored to the tenant later → the keys come back to life automatically (unless they expired in the meantime).

Privacy and trust

  • A key never grants more than you have. ALMAS rejects key creation if you try to grant a permission you don't hold.
  • A key cannot create more keys. The API Keys page itself, password change, and 2FA settings all reject key-authenticated requests — those require your real password.
  • A key cannot read or change data outside its tenant. The tenant binding is non-overridable.
  • Every call made with a key is audited — your tenant admin can see when a key was used, from what IP, against which endpoint.

Troubleshooting

If your integration suddenly stops working, check these in order:

  • 401 Unauthorized — the key is wrong, expired, revoked, or its grace window after a rotation ended. Check the API Keys list — does the key still show as active? If it's expired or revoked, rotate (or create a new key) and update the integration.
  • 403 Forbidden — the key is valid but the action isn't allowed. Either the key's abilities don't include the permission this endpoint needs, or you yourself lost that permission. Open the key on the API Keys page to see its current effective abilities. If the key is in mirror mode, ask your tenant admin which permission was removed from your account.
  • 403 Forbidden with "tenant mismatch" — the integration is sending a tenant= parameter that doesn't match the key's tenant. Remove the parameter (the key sets tenancy automatically) or fix it to match.
  • 429 Too Many Requests — you've hit the per-key rate limit. Check the Last used column on the list — if it's burning through requests, your integration is mis-configured (an infinite loop or aggressive polling). Wait, then either reduce its call frequency or raise the rate limit (up to the global 60/minute cap) on the key.
  • Key shows as never used — the integration isn't actually calling ALMAS. Check the integration's logs for the actual error.

Connecting an AI agent via MCP

ALMAS exposes a Model Context Protocol (MCP) endpoint so AI assistants can drive your data using the same key. From your perspective: paste a short config snippet into your AI client (Claude Code, Claude on the desktop, a custom GPT runtime), give it a key, and the assistant gains access to the 25-ish tools ALMAS exposes — listing projects, fetching task details, creating transactions, attaching files, and so on. The assistant only sees the tools your key has permission to use; an Accountant key can record expenses but cannot create projects.

The exact configuration syntax differs per AI client; your AI client's own docs cover where to paste it. The configuration includes the URL https://your-almas.example.com/mcp, your API key as the Authorization header, and the protocol version. Save the config, restart the AI client, and you'll see ALMAS tools appear in its tool list.

If the agent reports "0 tools available," that usually means the key has zero abilities on its tenant — open the key, check the permission set. If it reports auth errors, the key is wrong or expired (same troubleshooting as REST).

Tip. Treat the AI assistant the same way you'd treat any other 3rd-party integration: a narrow key (specific permissions, short expiry, IP-locked if possible) is much safer than a mirror-mode key with 365-day expiry.