# API keys

Part of the InboxWA API reference: https://inboxwa.online/docs/api . Full reference as one document: https://inboxwa.online/docs/api.md . OpenAPI: https://inboxwa.online/openapi.json

Every call is made with an API key, and keys are managed on the **API Keys** page in the sidebar. A workspace admin can create, edit, rotate and revoke keys there. Other members with the settings permission can see the list and each key’s activity. The same key-management calls are in the reference below; they need an admin, either a dashboard session or a full-access key created by an admin. A scoped key is refused with `scope_denied`.

## Create a key

- **Name it** after the integration, for example "Order sync". The name shows in the key list and in the activity log.
- **Choose the access.** Full access carries everything its creator can do. A read-only key can only read. A custom key holds exactly the scopes you choose; see [Scopes and permissions](https://inboxwa.online/docs/api/guide/scopes.md).
- **Set an expiry** if you want one, from 1 to 730 days. An expired key is refused with `key_expired`.
- **Set a rate limit** if you want one, from 10 to 100,000 requests per minute. Leave it blank for the default; see [Rate limits](https://inboxwa.online/docs/api/guide/rate-limits.md).
- **Copy the key now.** It starts with `iwk_` and is shown once. Only a SHA-256 hash is stored, so a lost key is replaced, never recovered.

## Manage a key

- **Edit** to rename a key or change its expiry or limit. Scopes are fixed when a key is created; to change them, create a new key.
- **Rotate** to get a replacement with the same name, scopes and limit. A grace period of up to 168 hours keeps the old key working while you switch over, then it stops on its own.
- **Revoke** to stop a key at once. This cannot be undone. Create and deploy the replacement first so nothing goes down.
- **Activity** shows each key’s calls for the last 7 or 30 days: method, path, status and IP, including refused and rate-limited calls. The log is kept for 30 days.
- A workspace can hold up to 20 active keys.

## Good practice

- One key per integration, so any one can be revoked alone.
- Scoped keys for integrations. A full-access key can also create and revoke keys, so if one leaks, so can everything it minted.
- Read-only keys for dashboards and reports.
- An expiry on keys you hand to a contractor or a trial.
- Keep keys on your server, in environment variables or a secrets manager. Never put one in a web page, a mobile app or a git repository.
- Rotate when someone who knew a key leaves, and check the last-used time on the list: a key nobody uses should not exist.

> **Which plan does what** Keys are part of Growth and Scale; Starter has none. On Growth a key can make the core calls: sending, creating and updating contacts, listing templates and Zapier. Any other call is refused with `api_access_not_enabled`, whatever the key’s scopes. On Scale a key can call everything. `GET /api/reporting/v1/whoami` shows which applies to yours. See [Plans and API access](https://inboxwa.online/docs/api/guide/plans.md).