Skip to main content

Authentication

Before we get started with Courier's Inbox, we need to talk about Authentication. The preferred way of building an inbox is to integrate with our components into your frontend and have these components talk directly to Courier's API. These API's are different than our normal endpoints at https://api.courier.com as our Inbox APIs have CORS (Cross Origin) enabled. When you first install the Courier provider, we do not require strict authentication beyond a public Client Keys and User ID.

If you haven't installed the Courier Provider yet, you can do so here.

Default (No Auth)​

To started with the Courier Provider, we do not require authentication beyond your Client Key and User ID. This is to help with development and help get you up and running. You can find your Client Key here.

Before going to production, you should implement stricter authentication as described below.

Courier Provider

JSON Web Token (JWT)​

When getting ready for production, we recommend implementing authentication in the form of a JWT. You can use our Issue Token API to make things easier. A JWT should be generated on a per-user level in your backend and be supplied to your frontend through an API or embedding in your HTML.

An example payload for an issue-token would look like:

{
  "scope": "user_id:{{USER_ID}} inbox:read:messages inbox:write:events"
}

JWT Expiration​

You can also set an expiration date for the JWT by providing the following scope:

{
  "scope": "user_id:{{USER_ID}} inbox:read:messages inbox:write:events",
  "expires_in": "2 days"
}

The result of this API will look like:

{
  "token": "MY_JWT_TOKEN"
}

This token will then be passed into the client components and serve as your per-user authentication.

HMAC (Deprecated)​

We recommend JWT over HMAC as JWT allows us to set more specific scopes.

HMAC is a way to add extra security to your application, more so than just having approved domains and a client key. HMAC allows you to generate a signature for each user you have in your system. It is a hash of your User ID and your API Key.

import crypto from "crypto";

const userSignature =
  crypto
    .createHmac("sha256", apiKey)
    .update(userId)
    .digest("hex");

Make sure you DO NOT do this on your frontend because your API Key is private and you do not want to leak it. This HMAC should be generated on the backend and either embedded in your frontend via SSR or can be returned with an API endpoint (for each user).