API Key Security Best Practices

Summary

This guide explains how to protect Tealfabric API keys across their full lifecycle, from creation to rotation and revocation. It focuses on practical controls you can apply immediately in production and non-production environments. Use these practices to reduce credential exposure risk while keeping integrations reliable.

Why API key security matters

API keys often grant direct access to business data and automation capabilities, so weak handling can create high-impact incidents. Secure key management lowers the chance of unauthorized access, limits blast radius when credentials are exposed, and supports audit readiness. Treat API keys as sensitive credentials from the moment they are created.

A strong approach combines technical controls and operational discipline. Secure storage, least-privilege scope design, regular rotation, and ongoing monitoring work best when applied together rather than in isolation. This combined model creates a safer and more predictable integration posture.

Store keys securely from day one

Store API keys only in server-side secret locations such as environment variables or dedicated secret managers. Never place keys in client-side code, plaintext config files in repositories, or team chat messages. Separating keys by environment, owner, and use case helps reduce accidental reuse and limits the impact of compromise.

Document each key with purpose, owner, and expected lifespan as soon as it is issued. This makes future rotation and incident response much faster because teams can identify affected systems quickly. Good key hygiene starts with traceability and controlled storage.

Use keys safely in requests

When calling Tealfabric APIs, send the key over HTTPS and include tenant context headers where required by your environment. Keep request examples server-side and avoid exposing secrets in browser bundles or logs. The examples below show the same authenticated read request pattern in TypeScript and JavaScript.

const baseUrl = "https://dev.tealfabric.io/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type Entity = {
  entity_id: string;
  name: string;
  status: string;
};

async function fetchEntity(entityId: string): Promise<Entity> {
  const response = await fetch(`${baseUrl}/entities?id=${encodeURIComponent(entityId)}`, {
    method: "GET",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as { data?: Entity };
  if (!payload.data) throw new Error("Missing entity payload");
  return payload.data;
}

curl -X GET "https://dev.tealfabric.io/api/v1/entities?id=<ENTITY_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "entity_id": "<ENTITY_ID>",
    "name": "Example Entity",
    "status": "active"
  }
}

Design scopes with least privilege

Give each key only the permissions required for a specific integration task. Broad scopes may feel convenient, but they increase the impact of key leakage and make auditing harder. Use separate keys for read-only reporting, process execution, billing integration, and administrative workflows whenever possible.

Avoid wildcard scope assignment unless there is a verified operational need and clear compensating controls. Review key scopes periodically to remove permissions that are no longer used. Least-privilege design is one of the highest-value controls for key risk reduction.

Rotate and expire keys on schedule

Key rotation limits exposure windows and helps you recover faster if credentials are leaked. A practical rotation flow is to create a replacement key, deploy it, validate traffic, revoke the old key, and monitor for regressions. This sequence minimizes downtime while preserving control.

Set expiration dates for all keys, including development keys, and align rotation frequency with risk level. Production keys should rotate more frequently than lower-risk environments, and any suspected compromise should trigger immediate rotation. Calendar reminders and ownership records help teams avoid expired-key outages.

Monitor usage and respond quickly

Track last-used timestamps, source IP patterns, usage volume, and revocation events to spot anomalies early. Sudden traffic spikes, usage from unexpected networks, or activity after expected retirement are high-signal indicators that need investigation. Monitoring should be paired with a documented response workflow so teams can act without delay.

If a key is compromised, revoke it immediately, assess impact, issue a replacement with constrained scopes, and update affected integrations. Then review logs, notify relevant stakeholders, and document corrective actions to prevent recurrence. Fast containment and disciplined follow-up are essential for reducing incident impact.

API key security checklist

Use this checklist when issuing or reviewing a key:

• Key is stored in a secure server-side secret location.
• Key has least-privilege scopes for its exact use case.
• Key has an owner, purpose, and environment label.
• Key has an expiration date and rotation schedule.
• Requests use HTTPS and required tenant headers.
• Key is not present in repositories, client code, or logs.
• Usage and anomaly monitoring are enabled.
• Incident response steps are documented and tested.

Related documentation

• API key management
• ProcessFlow API
• Security, privacy, and compliance