Developer Guide · Getting started

API keys & permissions

Every /api/v1 request is authenticated with an API key sent in the X-API-Key header. Here is how to create keys, what they can access, how plans gate them, and how to keep them safe.

Inboxi API keys belong to your organization, not to a person. Each key has a public part that you send with every request and a secret that you use to verify webhooks. Keys are created and revoked by admins in the dashboard.

Create an API key

1. 1
   Open the API Keys tab

   Go to Settings › Developer Hub › API Keys. You need the developer permission on your role (owners and admins have it).
2. 2
   Click + New API Key

   Give the key a name that says where it is used, for example Production backend or Staging, then click Create.
3. 3
   Copy the key and the secret

   A green panel shows the full key (inx_live_…) and its secret (sk_live_…). The secret is shown only once. Store both in your secrets manager before you dismiss the panel.
4. 4
   Use it from your server

   Send the key in the X-API-Key header. After creation the list only shows a masked version of the key, its status and when it was last used.

inboxi.app/settings/developer

1234

Key format and the header

GET /api/v1/contacts?search=ahmed HTTP/1.1
Host: inboxi.app
X-API-Key: inx_live_your_api_key
Content-Type: application/json

Permissions

Each key carries a list of permissions. Every endpoint requires one of them; a key without it gets403 with "error": "Missing permission: <name>". Keys created in the dashboard get the default set read, write, webhooks, widget and external_data.

Plan gating and FEATURE_LOCKED

Permissions say what a key may do; your plan says what your workspace may do. The developer API (api_access), webhooks and external data are part of the Growth plan and above. Starter workspaces can use the website widget and SDK only. When the plan does not include a feature, the request is rejected before it reaches the endpoint:

HTTP/1.1 403 Forbidden
{
  "success": false,
  "error": "This feature requires the Growth plan. Upgrade to unlock.",
  "code": "FEATURE_LOCKED",
  "feature": "api_access",
  "currentTier": "starter",
  "requiredPlan": "Growth",
  "upgradeUrl": "/settings/plans"
}

The canonical tier-to-feature map is public, so your own UI can gate features without hard-coding plan names. See Plans & features map.

curl https://inboxi.app/api/subscriptions/features-map

Security best practices

• Call the API only from your servers. A key in browser JavaScript, a mobile bundle or a public repository can be extracted and used to message your customers.
• Keep the key and secret in environment variables or a secrets manager, never in source control.
• Create one key per system and environment (production backend, staging, a partner integration) so you can revoke one without breaking the others.
• Watch the Last used time in the key list. A key that is used when you are not expecting it should be revoked.
• Verify every webhook with the secret and reject unsigned or stale payloads (see Webhooks).
• Never log full keys or secrets. Log the masked prefix if you need to tell keys apart.

Rotating and revoking keys

Rotate a key whenever someone who had access leaves, after a suspected leak, or on a fixed schedule.

1. 1
   Create the new key

   Click + New API Key and store the new key and secret alongside the old ones.
2. 2
   Deploy it

   Switch your services to the new key and confirm requests succeed (its Last used time starts updating).
3. 3
   Revoke the old key

   Click Revoke on the old key. It stops working immediately and is shown as Revoked. Delete removes it from the list entirely.
4. 4
   Recreate webhooks if needed

   A webhook copies the signing secret of your newest active key at the moment it is created. Existing webhooks keep their old secret, so delete and recreate them to move them to the new secret.