Managing API Keys
API keys let you call the IMAA REST API from scripts, CI pipelines, or your own services. They authenticate as your organisation — quota, tier, and resource access all come from the owning org, not the person who minted the key.
Keys are a Pro, Team, or Enterprise feature. Free tier sees an upgrade prompt instead of the management page.
When to use an API key
- Bulk-onboarding contracts from a terraform/pulumi pipeline
- Exporting alert history for compliance or billing
- Wiring IMAA into an internal dashboard
- Automating channel/rule updates during a deploy
If you only read the dashboard in a browser, you don't need a key — cookie auth is enough.
Creating a key
- Go to Settings → API Keys.
- Click + Create key. Give it a name you'll recognise later (e.g.
ci-prod,analytics-warehouse). - Choose a scope and any restrictions (see below).
- Optionally set an expiry — never, 90 days, or a custom date.
- Copy the key when it appears. This is the only time you'll see it.Paste it into your secret manager before closing the modal.
The dashboard shows only the prefix (e.g. imaa_abc12345…) after that — the full key is hashed with SHA-256 and never stored in plaintext.
Scope & restrictions
Scope lets you mint a key that does less than your dashboard user can. Default is read-write and unrestricted; tighten as needed.
| Option | Effect |
|---|---|
| Read-only | GET/HEAD/OPTIONS only. POST, PATCH, DELETE return 403. |
| Contract restriction | Pick a subset of your contracts. Calls touching any other contract return 403. |
| Chain restriction | Pick a subset of chains. Contracts on other chains return 403. |
| Expiry | First use after the expiry date auto-deactivates the key and returns 401. |
Restrictions are enforced on the API boundary — there's no way for a scoped key to elevate itself to an unscoped one.
Using the key in requests
Send the key as a Bearer token on every request:
Authorization: Bearer imaa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxQuick smoke test — who am I authenticated as?
curl https://imaa-api.w3i.io/api/v1/auth/me \
-H "Authorization: Bearer $IMAA_API_KEY"More examples on the Public API reference.
Tier limits
| Plan | Active keys | Requests / minute / key |
|---|---|---|
| Free | 0 | — |
| Pro | 5 | 300 |
| Team | 20 | 1,200 |
| Enterprise | Unlimited | 6,000 |
Revoked or expired keys don't count toward your active limit — the slot frees up as soon as you revoke.
Rotating a key
Use Regenerate on any active key to mint a fresh secret with the same name, scope, restrictions, and expiry. The old key is disabled immediately; any services still using it will start getting 401s, so roll the new value to your secret store first and then regenerate.
Regenerate is also the right move the moment you suspect a key has leaked — it's faster than deleting and recreating, and the audit log records it as a rotation rather than two unrelated events.
Revoking
Revoke flips the key to inactive immediately. Further requests return401. Revoked keys stay visible in your list with a Revoked badge so you have a record of what happened — we hard-delete them after 90 days.
Revocation is irreversible. If you revoke the wrong key, create a new one.
Usage dashboard
Click View usage on any key for a 30-day daily breakdown of requests and errors. Counters are kept in Redis and flushed to Postgres every 5 minutes, so very recent calls may not show up for a few minutes.
Handling errors
| Status | Meaning | What to do |
|---|---|---|
401 Unauthorized | Key is invalid, revoked, or expired. | Check the prefix in your secret store vs the dashboard. If it matches, the key was revoked or hit its expiry — create a new one. |
403 Forbidden | Key is valid but not allowed to do this. | Usually scope (read-only key doing a POST, or scoped key touching an out-of-scope contract/chain). Create a wider key if the use case warrants it. |
429 Too Many Requests | Rate limit exceeded for the tier. | Back off using the Retry-After header; consider a Team/Enterprise upgrade for heavier workloads. |
Security best practices
- Store keys in a secret manager (AWS Secrets Manager, GCP Secret Manager, 1Password, Vault). Never commit to git, paste into chat, or embed in client-side code.
- Use the minimum scope. If the service only reads, make it read-only. If it only touches one contract, restrict it. Compromise of a narrowly-scoped key is a much smaller incident than a read-write unrestricted one.
- Set expiry on keys you don't monitor. A 90-day default forces rotation and limits the blast radius of a forgotten key.
- One key per service. Separate CI, production, staging, and ad-hoc scripts. Easier to revoke one without blast-radius, easier to attribute usage spikes.
- Rotate on departure / exposure. Any time a teammate with access to the secret store leaves, or a laptop is lost, regenerate. It's a two-click operation.
- Watch the usage dashboard. An unexpected spike — or a sudden drop — is often the first signal that something has changed upstream of you.
Audit log
Every lifecycle event writes a row to the audit log: creation, revocation, regeneration, use-after-expiry, and scope denials. Org admins can review the log from the admin portal. Audit events include the key prefix but never the plaintext secret.