Platform›API Keys

API Keys

API keys authenticate your requests to the DiffHook API and identify which team's resources you're accessing. Each key has fine-grained scopes, optional expiration, and rotation support without downtime.

Creating a key

  1. Go to App → Settings → API Keys
  2. Click New API key
  3. Give it a descriptive label (e.g. production-server, ci-pipeline)
  4. Copy Client ID and Client secret immediately — they are shown only once

The Client ID is your public identifier: it starts with dh_live_. After creation, Settings lists each key by label and full Client ID so you can copy the id anytime; the secret is never shown again.

If you forget to copy the secret, delete the key and create a new one.

Key permissions

All keys currently have full access to your team's resources (monitors, logs, settings). Per-scope keys (read-only, logs-only, etc.) are on the roadmap.

If you need to restrict access today, create a separate team for read-only integrations and invite limited members there.

Signing secrets

Your signing secret is separate from your API key. It is used exclusively to sign outgoing webhook payloads so your server can verify they came from DiffHook.

Find it at App → Settings → API Keys → Signing secret.

See Verifying Signatures for how to use it.

Rotating a key

  1. Create a new key and update your applications to use it
  2. Verify the new key is working in production
  3. Delete the old key from App → Settings → API Keys

There is no key rotation shortcut that auto-replaces a key in place — always follow the create → migrate → delete flow to avoid downtime.

Rotating your signing secret

Go to App → Settings → API Keys → Rotate signing secret.

After rotation:

  • All future webhooks are signed with the new secret immediately
  • Deliveries in-flight may still carry the old signature
  • Update your server's secret before revoking the old one

Revoking a key

Delete the key from App → Settings → API Keys. Revocation is instant — the key can no longer be used to request new tokens.

However, bearer tokens already issued with that key remain valid until they naturally expire (up to 24 hours after they were generated).

Key security best practices

  • Never commit keys to source control. Use environment variables or a secrets manager (e.g. AWS Secrets Manager, Doppler, Vault).
  • Use one key per environment. Keep separate keys for development, staging, and production so you can revoke one without affecting others.
  • Rotate keys periodically. Treat any key older than 90 days as a candidate for rotation.
  • Monitor for leaks. If a key appears in a public repository or log, revoke it immediately and create a new one.

Troubleshooting authentication errors

401 Unauthorized

  • Credentials are missing, malformed, or the key has been revoked
  • For API keys: use a JWT from POST /api/oauth/token

403 Forbidden

  • The key is valid but doesn't have access to the requested resource (e.g. a monitor belonging to a different team)