Start with least privilege

Register each application with only the APIs it actually calls. When an application's scope matches its purpose, a leaked key exposes far less:

  • One application per project or environment, not one shared key for everything.
  • Separate applications for staging and production, so test traffic can never touch production data.
  • Revoke registrations your project no longer needs. See Applications and credentials.

Rotate credentials on a schedule

Treat every credential as short-lived, even if it doesn't expire on its own:

  1. Generate a new credential on your application page.
  2. Update your service to use it.
  3. Revoke the old credential once traffic has moved over.

Rotate at least every 90 days, and immediately after anyone with access leaves the team or a secret may have been exposed.

You can only see a key once

Store keys in a secrets manager or environment variables the moment you generate them. A key pasted into a ticket, chat message, or git history should be treated as compromised. Revoke it and rotate.

Prefer short-lived tokens

Where an API supports OAuth 2.0 client credentials, prefer them over long-lived API keys:

CredentialLifetimeBlast radius if leaked
API keyValid until revokedEverything the application can reach
OAuth 2.0 access tokenExpires in about an hourOne hour of scoped access

Cache tokens and refresh them before they lapse. See Authentication.

Verify every webhook

If you consume webhooks, verify the X-Signature header on every delivery using your signing secret, and reject anything that fails. Redeliveries mean duplicate events can arrive, so process events idempotently by their id. See Webhooks.

Protect data in transit

  • Only call the APIs over HTTPS. Requests over plain HTTP fail with a 4xx response; never disable certificate verification to work around one.
  • Keep your TLS stack current. Out-of-date clients are the most common cause of handshake failures.
  • Point webhooks at HTTPS endpoints with valid certificates. Unsigned or unverified endpoints invite forged events.

Handle failures without leaking data

Log status codes and request_id values, not full request bodies. Error payloads can contain customer data, and logs outlive the incident that produced them. See Errors.

Next steps