Skip to main content
Courier Inbox and Toasts use the same JWT-based authentication and scopes, since both connect to the same message feed. If you’ve already set up authentication for either, you can skip this step.

​
JSON Web Tokens (JWT) Authentication

JWTs are short-lived, signed tokens used to securely authenticate and authorize connections from Courier SDKs to the Courier backend. They are the recommended authentication method in all cases. JWT generation requires a private key which is unique to your Courier workspace, and should only be accessed in secure environments such as your backend server. A typical production JWT generation flow might look like this: JWT Authentication Flow Diagram
1

Your app calls your backend

When your app needs to authenticate a user, your app should make a request to your own backend (ex. GET https://my-awesome-app.com/api/generate-courier-jwt).
2

Your backend calls Courier

In your backend, use your Courier API Key to call the Courier Issue Token Endpoint and generate a JWT for the user.
3

Your backend returns the JWT to your app

Having received the JWT from Courier, your backend should return it to your app and pass it to the Courier SDK.
The JWT can be supplied to the Courier client at initialization time. See the docs for each SDK for detailed instructions and examples:

​
Testing JWTs in Development

To quickly get up and running with JWTs in development, you can use cURL to call the Courier Issue Token Endpoint directly. 
curl --request POST \
     --url https://api.courier.com/auth/issue-token \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer $YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data \
 '{
    "scope": "user_id:$YOUR_USER_ID write:user-tokens inbox:read:messages inbox:write:events read:preferences write:preferences read:brands",
    "expires_in": "$YOUR_NUMBER days"
  }'
Looking for backend code examples for generating JWTs? Check out the courier-samples repository for straightforward SDK implementations in popular languages and frameworks, such as Node.js, Python, Ruby, and more.

​
Client Key and HMAC Authentication (Deprecated)

Earlier versions of the Courier web SDKs support client key authentication with or without an HMAC signature. The latest versions (@trycourier/courier-react v8+ and @trycourier/courier-ui-inbox v1+) remove this support.We recommend upgrading to the latest SDKs and updating existing integrations to use JWT authentication.
HMAC authentication adds a hash-based code to the request to verify its authenticity. For requests to the Courier backend, the HMAC is a hash of the userId and your Courier API Key.
hmac.ts
import crypto from "crypto";

const userSignature =
  crypto
    .createHmac("sha256", courierApiKey)
    .update(userId)
    .digest("hex");
Always keep your Courier API keys private. Do not generate HMAC signatures in client-side code.

​
Troubleshooting

​
JWT errors

Messages not loading (401 or empty Inbox) The most common cause is an expired token or missing scopes. Decode your JWT at jwt.io and check:
  • exp — is the expiration in the future? Tokens with short expires_in values can silently expire between page loads. If your users keep sessions open for long periods, add a refresh mechanism that requests a new token before the current one expires.
  • scope — does it include inbox:read:messages and inbox:write:events? Without these, the SDK connects successfully but returns no messages. A minimal working scope string looks like:
user_id:<YOUR_USER_ID> inbox:read:messages inbox:write:events
Add read:preferences write:preferences if you use the embedded Preferences editor, and write:user-tokens if you sync push tokens from the client.

​
Cross-channel read sync

When cross-channel sync is enabled, reading a message in one channel (for example, opening an email) marks the corresponding Inbox message as read. This relies on a tracking pixel embedded in the email body. If your users’ email clients block tracking pixels (common in corporate environments with strict privacy policies), the read event never fires and the Inbox message stays unread. There is no workaround on the email side; you can call the Messages API to mark messages read programmatically if needed. To disable cross-channel sync entirely, enable optOutOfInboxSync in your Courier Inbox provider settings. This keeps Inbox message state independent of other channels.

​
Next Steps

Integrate an SDK

Courier SDKs are available for React, Web Components, React Native, Flutter, iOS, and Android.

Send a Message

Start sending notifications