API keys

API keys authenticate requests to the public REST API. Manage them under Settings → API keys. Seeing the list takes edit company settings; creating, editing and rotating keys also takes the API access permission. Revoking needs only edit company settings, so a leaked key is quick to stop.

Create a key

1. Name it and, if useful, say what it is for.
2. Pick live (production data) or test. A test key (mca_test_…) is answered by your sandbox tenant when one is provisioned; until then it can only read production.
3. Choose scopes: per resource, read or read + write (deals, merchants, leads, payments, submissions, ISOs, funders, syndicators, payouts, renewals, credit facilities, compliance, applications, communications, statement analysis, webhook endpoints, merchant bank accounts (masked), contracts, e-sign, documents). Write implies read. A key with only the scopes it needs is the one you want.
4. Tick any money moves it needs — fund a deal (deals:fund), mark payments paid or bounced (payments:settle), record refunds (payments:refund). They are never implied by write access, not even "all write", and can be added to or removed from an existing key from its row.
5. Optionally set an expiry and an IP allow-list (IPs or v4 CIDRs); requests from other addresses get 403.
6. Copy the token once; only a hash is stored.

A key can only do what you can. Each scope maps to the permission behind the same action on screen (deals write needs edit advances, funding needs activate advances, refunds need record refunds…). Scopes beyond your own permissions are greyed out, and the server refuses them.

Lifetime. A company setting (the longest key lifetime, in days) caps how long a key may last: a key made without an expiry gets the cap, a longer expiry is refused, and a rotation is cut to it. A week before any key expires, a task and a notification remind you to rotate it.

Use a key

Send it as a bearer token against your company host, and start with whoami:

curl -H "Authorization: Bearer mca_live_…" https://acme.mcamgr.com/api/v1/whoami

whoami returns the key's name, kind, scopes, expiry, the tenant it is pointed at and the rate limit — the first thing to check when an integration misbehaves. Every response carries X-Request-Id (quote it when reporting a problem) and X-RateLimit-Limit / X-RateLimit-Remaining.

Rotate, revoke, usage

Rotate issues a replacement with the same name, scopes, expiry and allow-list and keeps the old key alive for 24 hours so you can switch without downtime. Revoke stops a key immediately. The list shows each key's call count, last use and the address it was last used from.

Activity on a key lists its last 200 requests from the past 30 days — time, method, path, status, address and request id — so after a leak you can see what it read. Query strings and bodies are never recorded.

Legacy keys — made before scopes existed — show a legacy badge. They still work, read as the scopes their old flags imply, and their use is logged. Convert to explicit scopes turns one into an ordinary key with exactly the same access.

Limits

Each key may make 120 requests a minute, and all of the company's keys and connected apps together 600. Writes are refused with 503 (retry shortly) if the limiter itself is unavailable, rather than let through unmetered.

Can’t find what you need? Return to the app or contact your administrator.