Authentication

DiffHook uses OAuth 2.0 client credentials to authenticate API requests. You exchange an API key for a short-lived bearer token, then send that token on every request.

Step 1 — Get your API key

Go to App → Settings → API Keys and create a key. You will receive two values:

• Client ID (client_id) — public identifier. It starts with dh_live_ and continues with a random suffix (URL-safe characters).
• Client secret (client_secret) — private secret only.

Step 2 — Request a bearer token

Exchange your credentials for a token by calling POST /api/oauth/token with a form-encoded body:

Tokens are valid for 24 hours. Request a new one before the current one expires.

Step 3 — Use the bearer token

Pass access_token in the Authorization header on every API call:

curl https://www.diffhook.com/api/monitors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Error responses

Missing or malformed Authorization header (401):

{ "error": "Authorization header missing or invalid" }

Expired or tampered token — re-authenticate to get a new one (401):

{ "error": "Invalid or expired token" }

Bad credentials at the token endpoint return an OAuth error body (401):

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Security best practices

• Never commit your client_secret to source control
• Store credentials in environment variables (DIFFHOOK_CLIENT_ID, DIFFHOOK_CLIENT_SECRET)
• Tokens expire after 24 hours — build automatic re-authentication into your integration
• Rotate keys immediately if one is leaked — revoke the old key in Settings, generate a new one

Key rotation

To rotate without downtime:

1. Generate a new key in Settings → API Keys
2. Request a token with the new credentials and deploy your app with it
3. Revoke the old key once traffic has fully shifted