API Keys — Authenticating to the Macha REST API

What API keys are for

API keys let your own code call the Macha REST API. They live on your servers (never in client-side JavaScript or mobile apps that ship to end users) and they authorize every request to /api/v1/*. Use them to embed Macha agents into your own product, sync agent configuration from a source of truth, push conversation data into your own analytics stack, or trigger Macha from any system that can send an HTTP request.

Each key is bound to a single organization. A key issued for Org A cannot read, write, or even discover data in Org B, regardless of what IDs you put in the URL or body. See the API Reference for the full endpoint list.

Generating a key

Keys are managed from Settings → API Keys in the dashboard. Only organization admins can create or revoke keys.

1. Click Create API key.
2. Give it a label that describes what it's used for (e.g. "Production sync job", "Internal CRM webhook"). The label is visible in the key list and in audit logs.
3. Pick the scopes the key needs (see below). Default is read-only.
4. Optionally set an expiry date. Keys without an expiry never auto-expire; you have to revoke them manually.
5. Click Generate. The full key is shown once, in a one-time reveal modal. Copy it immediately and store it somewhere secure (a password manager, your secrets vault, a CI variable). Macha cannot show it again.

Using a key

Every API request must include the key as a Bearer token in the Authorization header:

curl https://dashboard.getmacha.com/api/v1/conversations \
  -H "Authorization: Bearer mka_live_..."

All keys start with the prefix mka_live_. The prefix is a useful tripwire for secret scanners (GitHub, GitGuardian, your own CI) to flag committed keys before they hit production.

Responses are standard JSON with HTTP status codes. 200 on success, 401 if the key is missing or revoked, 403 if the key doesn't carry the required scope, 429 if you've hit the rate limit, and 4xx/5xx for the usual reasons. Error responses always include a structured { code, message } body so your client can branch on the code.

Scopes

Scopes are per-resource and per-action. A key carries an explicit list, and the match is exact: a key with agents:read does not automatically gain agents:write. This makes a key's privileges fully visible from its scope list alone.

• agents — agents:read, agents:write, agents:delete
• conversations — conversations:read, conversations:write, conversations:delete
• connectors — connectors:read, connectors:write, connectors:delete
• custom tools — custom_tools:read, custom_tools:write, custom_tools:delete
• sources — sources:read, sources:write, sources:delete
• chatbots — chatbots:read, chatbots:write, chatbots:delete
• triggers — triggers:read, triggers:write, triggers:delete
• team — team:read, team:write, team:delete
• analytics — analytics:read
• org — org:read

The dashboard creation modal offers convenient "tick all read" and "tick everything" shortcuts so you don't have to click each box individually for the common cases. For production credentials, prefer the minimum scopes the job actually needs, not the convenient maximum.

Rate limits

Limits are applied per API key, not per organization. Two windows run in parallel:

• 1,000 requests per minute
• 10,000 requests per hour

When you hit a limit you'll get a 429 Too Many Requests response with a Retry-After header indicating how many seconds until the window resets. Back off, then retry. The limits are generous for normal automation; if you're hitting them consistently you're likely better off batching or moving to a streaming/webhook pattern.

Because limits are per-key, one noisy integration in your workspace can't starve another. Issue a separate key per integration so you can isolate rate-limit blame.

Plan availability

API keys are available on every paid plan. Trial accounts can generate keys for testing; production usage requires an active subscription. Plan-level limits (agent count, scheduled triggers, custom tools, etc.) apply identically whether you're hitting Macha from the dashboard or the API.

Security hygiene

The usual rules apply, but the ones worth calling out for Macha specifically:

• Never commit a key to a repository. Use environment variables, a secrets manager, or your CI's encrypted variable store. The mka_live_ prefix is recognised by most secret scanners.
• Rotate keys quarterly at minimum, or immediately on any suspected leak. Revoke first, then generate a replacement, then update consumers.
• One key per integration. Don't share a single "admin key" across services. Per-integration keys mean a leak only affects one surface, and you can rotate without coordinating outages across teams.
• Set an expiry on keys you give to short-lived projects. Auto-expiring credentials beat remembering to revoke.
• Server-side only. Never put a Macha API key in a browser bundle, a mobile app, or a public-facing JavaScript file. If you need browser-side access to Macha data, route it through your own server with its own auth.

Revoking a key

From Settings → API Keys, click the menu next to any key and select Revoke. Revocation takes effect immediately — the next request with that key will return 401. There's no grace period and no undo, so update consumers first (or have the replacement key ready) before revoking the old one.

Revoked keys remain in the audit list so you can see when they were last used and by whom they were created. They cannot be reactivated; generate a new key if you need to restore access.

Audit log

Each key shows its label, prefix, scopes, creator, creation date, and the timestamp of its most recent use. The "last used" timestamp updates on every successful request and is the easiest way to spot abandoned keys that should be cleaned up.

If you're tracking down which key did what, the prefix (the first 8 characters after mka_live_) is shown on every audit row and is the same prefix that appears in any logs we keep server-side. Match on prefix, not on the full key — Macha never logs the full key.