DiffHook/Docs
Platform›API Keys

API Keys

API keys authenticate your requests to the DiffHook API and identify which team's resources you're accessing.

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 the key immediately — it is shown only once

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

Using your key

Pass the key in the Authorization header on every API request:

Authorization: Bearer dh_live_xxxxxxxxxxxxxxxxxxxx

Keys starting with dh_live_ are live keys. All API requests made with them affect real data.

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 — any request using that key returns 401 Unauthorized immediately.

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

  • The key is missing, malformed, or has been revoked
  • Verify the Authorization: Bearer <key> header is present and correct

403 Forbidden

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