Skip to main content
All requests to the Wacht Backend API must be authenticated. Wacht uses standard HTTP Authorization headers with Bearer tokens. There are two distinct methods for authenticating against the Wacht API, depending on the context of the request.

​
Standard API Keys (Server-to-Server)

If your backend code is communicating with Wacht on behalf of your application (e.g., synchronizing users, validating organization state, fetching webhooks), you must use a Secret API Key. Secret API Keys carry full administrative privileges for your deployment. Never expose them in client-side code like React or React Native.

​
Providing the API Key

You must attach your API Key to every request via the Authorization header. You must also include the X-Deployment-ID header to specify which deployment you are targeting, as your API key may have access to multiple. 
curl -X GET "https://api.wacht.dev/v1/users" \
  -H "Authorization: Bearer " \
  -H "X-Deployment-ID: depo_123456789"
If you are using one of the official Wait SDKs (like wacht-rs), this header injection is handled automatically for you based on your environment configuration.

​
JWT Session Tokens (Client-to-Server)

If a user is communicating with your API (or directly with specific unprivileged Wacht endpoints) and providing a Wacht JWT, you can validate and use that JWT. When Wacht issues a JSON Web Token (JWT) to an authenticated client, the token contains specific claims about the user’s identity (sub) and their active active session (session_id). 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
While you will primarily use the Wacht SDKs to validate these JWTs locally, some Backend APIs (like the API Auth App and Webhook App frontend portals) require clients to pass these JWTs forward.

​
Status Codes

Failing to provide correct authentication credentials will result in standard HTTP error responses:
HTTP StatusMeaningResolution
401 UnauthorizedMissing or invalid Bearer token.Ensure the Authorization: Bearer <token> header is present and the token is correct.
403 ForbiddenThe token is valid, but lacks the necessary permissions to access the resource.Check the token’s scope or organization permissions.