Skip to main content

API Keys

API keys are long-lived credentials issued at the tenant level. External systems use them to authenticate machine-to-machine requests against the Azotte REST API.

This page covers how to create, rotate, and use API keys, plus the security rules every integration must follow.

Portal-Only Management​

API keys cannot be created, modified, or revoked through the REST API. All key lifecycle operations — issue, rotate, scope change, revoke — must be performed by a Tenant Admin in the Azotte portal under Settings → Developers → API Keys.

This is intentional. It prevents a compromised key from issuing new keys, escalating its own scope, or rotating itself to evade revocation. The portal enforces human approval, audit logging, and MFA on every key operation.

The API only consumes keys (via the Authorization: Bearer header); it never manages them. :::

When to Use​

  • Backend services calling Azotte APIs on behalf of your tenant.
  • Webhook signature verification setup (paired with the signing secret).
  • CI pipelines, schedulers, and internal tooling that need automated access.

Do not ship API keys to browsers, mobile apps, or any client your customers can inspect. For customer-facing flows use short-lived session tokens issued by your backend.

Create an API Key in the Portal​

  1. Sign in to the Azotte portal as a Tenant Admin.
  2. Open Settings → Developers → API Keys.
  3. Click Create API Key.
  4. Enter a descriptive name (for example billing-service-prod).
  5. Select the environment: Sandbox or Live.
  6. Choose the role that defines the key's scope.
  7. Click Generate.
  8. Copy the key value immediately. Azotte shows the full key only once.

Create API key dialog — Settings → Developers → API Keys, with name, environment, and role fields visible

Screenshot needed: portal capture of the Create API Key dialog showing the Name, Environment (Sandbox/Live), and Role dropdowns, plus the one-time key reveal panel. Place file at academy/static/img/portal/api-keys/create-step1.png.

Store the key in your secret manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, GitHub Actions secrets, etc.) before closing the dialog.

Use the Key in API Requests​

Send the key in the Authorization header as a bearer token. Include the x-tn header with your tenant identifier on every request.

curl https://api.azotte.com/v1/customers \
  -H "x-tn: <your-tenant-id>" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json"
const res = await fetch("https://api.azotte.com/v1/customers", {
  headers: {
    "x-tn": process.env.AZOTTE_TENANT_ID,
    "Authorization": `Bearer ${process.env.AZOTTE_API_KEY}`,
    "Content-Type": "application/json",
  },
});
var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-tn", Environment.GetEnvironmentVariable("AZOTTE_TENANT_ID"));
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AZOTTE_API_KEY"));

Rotate a Key​

Rotate keys on a fixed schedule (every 90 days is a common baseline) and immediately after any suspected exposure.

  1. Generate a new key with the same role and environment.
  2. Deploy the new key to all consuming services. Run both keys in parallel during the rollout window.
  3. Verify traffic is flowing on the new key in your access logs.
  4. Revoke the old key from Settings → Developers → API Keys.

Revoke a Key​

  1. Open Settings → Developers → API Keys.
  2. Locate the key by name.
  3. Click Revoke.
  4. Confirm. Revocation takes effect within seconds across all Azotte regions.

Revoked keys cannot be reactivated. Issue a new key if access is needed again.

Security Rules​

  • Never commit keys to git. Use environment variables or a secret manager.
  • Use one key per service. Do not share a key across unrelated workloads.
  • Apply the principle of least privilege: assign the narrowest role that lets the service do its job.
  • Use separate keys for Sandbox and Live. Never reuse a Sandbox key in production.
  • Monitor unusual usage: spikes, requests from new IP ranges, or 4xx clusters in your access logs.
  • Set up alerts on the audit log for apiKey.created, apiKey.revoked, and apiKey.usedFromNewIp events.
  • Roles - define what an API key is allowed to do.
  • Terminology - definitions of Tenant, x-tn Header, and API Key.
  • Getting Started - full integration walkthrough.