API keys

API keys are how AI agents (Claude, Cursor, custom bots) and external integrations read your Cash Runway data. Keys are issued, scoped, audited, and revoked from Settings → API keys.

Every key:

• Starts with the prefix cr_live_ so it's recognisable on sight.
• Is shown to you once, at the moment of creation. Cash Runway stores a one-way hash; we cannot reveal a key again.
• Carries one or more scopes — the permissions you grant it. Pick the narrowest set the integration actually needs.

Create a key

1. Open Settings → API keys.
2. Click Create API key.
3. Give it a label (e.g. "Claude — finance assistant").
4. Tick the scopes the integration needs:
   • READ_BANK — bank balances, reconciled and statement.
   • READ_FORECAST — cash position, 13-week forecast.
   • READ_PIPELINE — pipeline / projected revenue.
   • READ_INVOICES — AR invoices and AP bills (with optional line-item expansion). See Agent data scopes.
   • READ_CONTACTS — customers and suppliers, including a per-contact drill (LTV, payment cadence, ABC tier).
   • READ_SUMMARY — composite /daily-summary endpoint. The recommended starting point for a generic AI assistant.
5. (Optional, danger zone) Tick 🔒 Include sensitive accounts — see Sensitive accounts and contacts.
6. Click Create key. The secret is revealed once — copy it now.

The key carries a small chip showing Last used so you can spot abandoned integrations. Active keys can be rotated (issues a new secret, revokes the old one immediately) or revoked (kills the key).

For the modern crun_* USER and PARTNER keys (Settings → API keys / Partner → API keys), rotation is a create-new + revoke-old pattern — there's no dedicated rotate primitive. See the API key rotation runbook for the full walkthrough.

Agent data scopes

These scopes cover the agent data endpoints. Tick the narrowest combination the integration actually needs.

Scope	Grants access to	Notes
READ_INVOICES	GET /api/agent/invoices (AR), GET /api/agent/bills (AP)	Cursor-paginated. Filterable by status, contact, date range. Add ?lines=true to include each invoice's line items.
READ_CONTACTS	GET /api/agent/contacts (list), GET /api/agent/contacts/{id} (drill)	The drill returns LTV, last invoice / bill, expected purchase cadence, payment-days median, and ABC tier.
READ_SUMMARY	GET /api/agent/daily-summary	Composite "how's my business going today?" surface. Returns cash today, last-7d activity, AR aging, anomaly count, 13-week forecast headline, plus a deterministic prose narrative field an LLM can quote verbatim. Recommended starting point for a generic AI assistant.

Sensitive-data gating (see below) applies to every scope above automatically. A key without READ_SENSITIVE gets totals + reconciled amounts but never sees the names of accounts or contacts you've flagged.

Existing keys keep working

If you provisioned a key before these scopes were introduced, they are granted to your key automatically. You don't need to rotate or recreate. Newly created keys default to the explicit picks on the create-key dialog (no auto-grant).

Sensitive accounts and contacts

Some Xero accounts hold information you may not want every API key to see:

• Wages, Superannuation, PAYE / PAYG — payroll detail.
• Director loans, owner-equity accounts — personal balances.
• A specific contact — a confidential customer or a personal supplier.

Cash Runway lets you flag these accounts and contacts as sensitive (see Sensitive accounts for how to flag them). Flagged rows are hidden from every API key by default.

The READ_SENSITIVE scope

To let a specific key through the filter, tick 🔒 Include sensitive accounts on the create-key dialog. This adds the READ_SENSITIVE scope to the key.

• The toggle is a danger zone — it sits on its own amber row below the other scopes, with the subtitle "Defaults OFF. Only enable for keys you fully trust (e.g. your own agent, not a third-party integration)."
• The scope cannot be added to an existing key. To grant the scope to a key that already exists, rotate-and-recreate. This keeps the grant auditable.

Keys carrying READ_SENSITIVE show an amber 🔒 badge next to the label in the active keys table.

What changes for a key with READ_SENSITIVE

Endpoint kind	Without the scope	With the scope
List endpoints like /bank-accounts	Sensitive rows are absent. The response carries redactedItemCount: N so the agent knows N rows were withheld.	All rows present.
Composite endpoints like /cash-position, /forecast	Totals reconcile (the cash position sum, the forecast closing-cash trajectory). Per-account names are rewritten to "Sensitive account". The account code and external ID are blanked.	All names visible.

Totals reconcile, names redact. Amounts and IDs are never touched. Your bank statement always matches what the agent sees.

Audit: who used the sensitive scope, and when

The active keys table carries two timestamps per key:

• Last used — most recent agent API call by this key, period.
• Last sensitive access — most recent call by this key while it carried the READ_SENSITIVE scope. Only populated for keys that hold the scope.

The two diverge when a key has the scope but isn't actively using the agent API. A "Last sensitive access: 2 months ago" line is your cue to revoke.

Audit rows are never deleted, so the trail survives key rotation and revocation. Internally each agent request writes a row tagged usedSensitive: true when the calling key holds the scope; the timestamp on the key page is the most recent such row.

Partner (Advisor) keys

Keys minted from the Partner Portal (Partner → API keys, or the "Generate an API key" card on the Partner home) work differently from the per-account org keys above: an Advisor key is full access. Every partner key carries all seven capability scopes — including READ_SENSITIVE — so your firm sees the complete, unredacted financial picture for the clients it's linked to. There is no per-scope picker: the only choice you make when minting is org reach.

• All my linked organisations — the key follows your firm's live advisory link set. Organisations linked later become callable automatically, with no re-mint.
• Select specific organisations — pin the key to an explicit subset. Future links won't extend its reach (these show a Pinned badge in the list).

In the keys list, a full-access partner key shows Full access in place of the scope enumeration. (Older keys minted before this change may show a narrower scope list or, for keys from the original deferred-scope mint, a dash — rotate-and-recreate to upgrade them to full access.)

Rotate or revoke a key

• Rotate — issues a fresh secret, revokes the old one immediately. Use this when a teammate has left or when a key may have been pasted into a public place. The new secret is shown once.
• Revoke — kills the key. Cannot be undone. The key prefix and label stay visible in the Revoked keys table for audit.

Revoked keys instantly return 401 Unauthorized on every agent endpoint.

Related

• Sensitive accounts and contacts — how to mark a Xero account or contact as sensitive.
• Agentic API — Example calls — curl, TypeScript, Python snippets you can hand to an agent.
• API Reference — full endpoint catalogue.