← All articles

Managing API Keys

API keys authenticate your code when calling the Blocx API. Treat them like passwords — never check them into source control or paste them in chat. Manage all keys at API Keys.

Creating a key

  1. Open API Keys.
  2. Click Create key.
  3. Give the key a descriptive name — production-backend, staging, analytics-readonly, etc.
  4. Optionally attach a permission set that limits which resources and actions the key can use.
  5. Click Create.

You'll receive two values: an access key ID and a secret access key. The secret is shown once. Copy both to your secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, 1Password, etc.) before closing the dialog. If you lose the secret you must create a new key — we cannot recover it.

Permissions

Each key can be attached to a permission set that toggles access per resource and action. Built-in resources include messages, email, twofa, twofa_templates, mailboxes, campaigns, brands, numbers, messaging_profiles, webhooks, and quotas. Actions vary per resource (e.g., messages.send, messages.read; twofa.create, twofa.check).

A key without a permission set inherits the organization defaults. Tighten scope by creating a dedicated permission set under the Permissions section.

Using the key

Every request sends two headers:

curl -X POST https://api.otterblocx.com/messaging/send \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "+15551234567", "to": "+15557654321", "body": "Hello", "type": "SMS" }'

Or with the SDK:

import { createBlocxClient } from '@otterlabs/blocx'

const { client } = createBlocxClient({
  accessKeyId:     process.env.BLOCX_ACCESS_KEY_ID!,
  secretAccessKey: process.env.BLOCX_SECRET_ACCESS_KEY!,
})

Full reference at api.otterblocx.com/docs.

Rotating keys

Best practice is to rotate keys periodically, and immediately when a team member with access leaves.

The zero-downtime rotation pattern:

  1. Create a new key at API Keys with the same permissions.
  2. Deploy the new key to your application via your secret manager.
  3. Verify traffic is flowing on the new key — the Last used timestamp updates within seconds.
  4. Revoke the old key.

Revoking a key

Click the actions menu on a key and choose Revoke. Any requests using that key immediately return 401 Unauthorized. Revocation is irreversible.

Inspecting usage

The API Keys page shows last-used timestamps, the attached permission set, who created the key, and when. Use this to spot dormant keys you can clean up.

Tips

Related articles