Authenticate users with a JWT

This is the auth model for every Courier client SDK. One sign-in covers Inbox, Toasts, the preference center, and mobile push tokens.

Courier’s client SDKs authenticate with a JWT (JSON Web Token). Your backend mints a short-lived, scoped token with your Courier API key, and the SDK signs the user in with it. Inbox and Toasts read the same scopes. The preference center and mobile push each add their own. covers embedding the components first.

How the JWT flow works

The private API key that signs a JWT stays on your server, so your backend mints every token, never client code:

Your app calls your backend

When a user signs in, your app requests a token from your backend (for example, GET /api/courier-jwt).

Your backend calls Courier

Your backend uses your to call the with the scopes the user needs. Keys are per . Use the one matching the environment you’re issuing tokens for.

Your backend returns the JWT to the client

The client passes the token to the SDK through signIn({ userId, jwt }).

1. Issue a token

Call from your backend with your API key and a scope string:

const { token } = await client.auth.issueToken({
  scope: "user_id:user_123 inbox:read:messages inbox:write:events",
  expires_in: "2 days",
});

response = client.auth.issue_token(
    scope="user_id:user_123 inbox:read:messages inbox:write:events",
    expires_in="2 days",
)

curl --request POST \
  --url https://api.courier.com/auth/issue-token \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "user_id:user_123 inbox:read:messages inbox:write:events",
    "expires_in": "2 days"
  }'

response = courier.auth.issue_token(
  scope: "user_id:user_123 inbox:read:messages inbox:write:events",
  expires_in: "2 days"
)

response, err := client.Auth.IssueToken(context.TODO(), courier.AuthIssueTokenParams{
  Scope:     "user_id:user_123 inbox:read:messages inbox:write:events",
  ExpiresIn: "2 days",
})

AuthIssueTokenParams params = AuthIssueTokenParams.builder()
    .scope("user_id:user_123 inbox:read:messages inbox:write:events")
    .expiresIn("2 days")
    .build();

var response = client.auth().issueToken(params);

$response = $client->auth->issueToken(
    scope: 'user_id:user_123 inbox:read:messages inbox:write:events',
    expiresIn: '2 days',
);

var response = await client.Auth.IssueToken(new AuthIssueTokenParams
{
    Scope = "user_id:user_123 inbox:read:messages inbox:write:events",
    ExpiresIn = "2 days"
});

courier auth issue-token \
  --scope "user_id:user_123 inbox:read:messages inbox:write:events" \
  --expires-in "2 days"

With Courier MCP, issue a two-day inbox token for user_123.

Scopes

scope is one space-separated string. Copy the line for what you are building, and swap in your user’s id.

The user_id is yours, not Courier’s.
Use whatever your app already calls this user, such as a database id or your auth provider’s sub. Nothing has to exist in Courier first, since signing in registers the user. The same id goes in two places, user_id: in the scope and the userId you pass to signIn, and they have to match.

Inbox and Toasts

user_id:user_123 inbox:read:messages inbox:write:events

Add the preference center

user_id:user_123 inbox:read:messages inbox:write:events read:preferences write:preferences

Add mobile push

user_id:user_123 inbox:read:messages inbox:write:events write:user-tokens

Everything

user_id:user_123 inbox:read:messages inbox:write:events read:preferences write:preferences write:user-tokens read:brands

Every string starts with user_id: and the two inbox scopes. What each one grants:

Scope	Grants
`user_id:user_123`	Binds the token to one user. Always required.
`inbox:read:messages`	Read the user’s inbox messages.
`inbox:write:events`	Mark messages read, opened, archived.
`read:preferences` `write:preferences`	The embedded .
`write:user-tokens`	Sync from a mobile client.
`read:brands`	Apply a to the rendered inbox.

For every scope value, see the . Signing in tells the SDK which user it is fetching messages for. Until it runs, the components render empty. Pass the JWT to signIn when your app starts or the user logs in:

import { useEffect } from "react";
import { useCourier } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    // jwt is the token your backend issued in step 1
    courier.shared.signIn({ userId, jwt });
  }, []);

  // ... render <CourierInbox /> or <CourierToast />
}

<script type="module">
  import { Courier } from "@trycourier/courier-ui-inbox";

  // jwt is the token your backend issued in step 1
  Courier.shared.signIn({ userId, jwt });
</script>

<script setup lang="ts">
import { onMounted } from "vue";
import { useCourier } from "@trycourier/courier-vue";

const courier = useCourier();

onMounted(() => {
  // jwt is the token your backend issued in step 1
  courier.shared.signIn({ userId, jwt });
});
</script>

import { Component, OnInit, inject } from "@angular/core";
import { CourierService } from "@trycourier/courier-angular";

@Component({ selector: "app-root", standalone: true, template: `...` })
export class AppComponent implements OnInit {
  private readonly courier = inject(CourierService);

  ngOnInit(): void {
    // jwt is the token your backend issued in step 1
    this.courier.signIn({ userId, jwt });
  }
}

import Courier_iOS

// jwt is the token your backend issued in step 1
func authenticate() async {
  await Courier.shared.signIn(userId: userId, accessToken: jwt)
}

// signIn is a suspend function; call it from a coroutine
lifecycleScope.launch {
  // jwt is the token your backend issued in step 1
  Courier.shared.signIn(userId = userId, accessToken = jwt)
}

// jwt is the token your backend issued in step 1
Future<void> authenticate() async {
  await Courier.shared.signIn(accessToken: jwt, userId: userId);
}

import { useEffect } from "react";
import Courier from "@trycourier/courier-react-native";

export default function App() {
  useEffect(() => {
    // jwt is the token your backend issued in step 1
    Courier.shared.signIn({ accessToken: jwt, userId });
  }, []);

  // ... render <CourierInboxView />
}

3. Read the signed-in user

Every platform exposes the current user and a listener that fires on sign-in and sign-out. Use the listener to clear app state on sign-out, or to re-render once credentials are restored on launch.

import { useCourier } from "@trycourier/courier-react";

const { auth } = useCourier();
auth.userId;  // undefined when signed out

<script type="module">
  import { Courier } from "@trycourier/courier-ui-inbox";

  const listener = Courier.shared.addAuthenticationListener(({ userId }) => {
    console.log(userId ?? "No user signed in");
  });

  listener.remove();
</script>

<script setup lang="ts">
import { useCourier } from "@trycourier/courier-vue";

const courier = useCourier();
courier.auth.value.userId;  // undefined when signed out
</script>

import { CourierService } from "@trycourier/courier-angular";

// auth$ emits on every sign-in and sign-out
this.courier.auth$.subscribe(({ userId }) => {
  console.log(userId ?? "No user signed in");
});

Task {
  let userId = await Courier.shared.userId
  let isSignedIn = await Courier.shared.isUserSignedIn

  let listener = await Courier.shared.addAuthenticationListener { userId in
    print(userId ?? "No user signed in")
  }

  listener.remove()
}

val userId = Courier.shared.userId
val isSignedIn = Courier.shared.isUserSignedIn

val listener = Courier.shared.addAuthenticationListener { userId ->
  print(userId ?: "No user signed in")
}

listener.remove()

final userId = await Courier.shared.userId;
final tenantId = await Courier.shared.tenantId;
final isSignedIn = await Courier.shared.isUserSignedIn;

final listener = await Courier.shared.addAuthenticationListener((userId) {
  print(userId ?? "No user signed in");
});

await listener.remove();

const userId = await Courier.shared.getUserId();
const tenantId = await Courier.shared.getTenantId();
const isSignedIn = await Courier.shared.isUserSignedIn();

const listener = await Courier.shared.addAuthenticationListener({
  onUserChanged: (userId) => console.log("User changed:", userId),
});

await listener.remove();

On mobile, credentials persist across app sessions. The SDK restores the last signed-in user on launch, so no cold start needs signIn. Call it again only when the user changes or the token expires.

4. Sign out

Call signOut when the user logs out of your app. It clears stored credentials, disconnects the real-time socket, and on mobile stops associating push tokens with that user.

const { auth } = useCourier();
auth.signOut();

Courier.shared.signOut();

const courier = useCourier();
courier.auth.value.signOut();

this.courier.signOut();

Task {
  await Courier.shared.signOut()
}

lifecycleScope.launch {
  Courier.shared.signOut()
}

await Courier.shared.signOut();

await Courier.shared.signOut();

5. Refresh tokens

Set expires_in to match your session length. A short-lived token can expire while a tab stays open, which silently empties the inbox. The SDKs do not refresh tokens. Before the current token expires, mint a new JWT on your backend and call signIn again with it.

expires_in is optional, and omitting it mints a token that never expires. Always set it. A leaked token with no exp grants that user’s inbox forever. The only fix is rotating the API key that signed it.

EU-hosted workspaces

Skip this section unless your workspace is on the . Every client SDK defaults to Courier’s US hosts. Pass regional URLs through apiUrls on signIn:

import { getCourierApiUrlsForRegion } from "@trycourier/courier-react";

courier.shared.signIn({
  userId,
  jwt,
  apiUrls: getCourierApiUrlsForRegion("eu"),
});

import { Courier, EU_COURIER_API_URLS } from "@trycourier/courier-ui-inbox";

Courier.shared.signIn({
  userId,
  jwt,
  apiUrls: EU_COURIER_API_URLS,
});

import { getCourierApiUrlsForRegion } from "@trycourier/courier-vue";

courier.shared.signIn({
  userId,
  jwt,
  apiUrls: getCourierApiUrlsForRegion("eu"),
});

import { getCourierApiUrlsForRegion } from "@trycourier/courier-angular";

this.courier.signIn({
  userId,
  jwt,
  apiUrls: getCourierApiUrlsForRegion("eu"),
});

await Courier.shared.signIn(
  userId: userId,
  accessToken: jwt,
  apiUrls: .eu
)

Courier.shared.signIn(
  accessToken = jwt,
  userId = userId,
  apiUrls = CourierClient.ApiUrls.eu()
)

await Courier.shared.signIn(
  accessToken: jwt,
  userId: userId,
  apiUrls: CourierApiUrls.eu,
);

import { getCourierApiUrlsForRegion } from "@trycourier/courier-react-native";

await Courier.shared.signIn({
  userId,
  accessToken: jwt,
  apiUrls: getCourierApiUrlsForRegion("eu"),
});

The web packages re-export three helpers from @trycourier/courier-js:

Helper	Returns
`EU_COURIER_API_URLS`	Frozen EU preset (`api.eu.courier.com`, `inbox.eu.courier.io`, `realtime.eu.courier.io`).
`DEFAULT_COURIER_API_URLS`	Frozen US preset, the default.
`getCourierApiUrlsForRegion(region)`	A mutable copy for `"us"` or `"eu"`, so you can override a single host.

Mint the JWT against the same region as the client. For EU, your backend must call https://api.eu.courier.com/auth/issue-token. A US-issued token will not authenticate against EU hosts.

For the CourierApiUrls type shape, see .

Troubleshooting

The inbox loads but shows no messages. The SDK connects and throws nothing, so check these four causes in order. Decode the JWT at jwt.io for the first three:

exp is in the future. A token that expired between page loads signs in without error and returns nothing.
scope includes inbox:read:messages and inbox:write:events. Without them the connection succeeds and the feed is empty.
The user_id: in the scope matches the userId you pass to signIn. A mismatch reads an empty inbox belonging to whoever the token names.
The tenantId matches the send. A tenantId filters the feed, and the unread count, to that tenant. A message sent without a tenant, or in a different one, will not appear. Signing in without a tenantId applies no filter. See .

Preferences editor is empty or read-only. Add read:preferences write:preferences to the scope string. Push tokens never appear on the user. Add write:user-tokens to the scope string. covers the registration that follows. Everything 401s on an EU workspace. The token and the client must be in the same region. Confirm your backend mints against https://api.eu.courier.com/auth/issue-token and the client passes EU apiUrls.

FAQ

Why does the inbox connect but show no messages?

The token signed in but lacks read access. Confirm the scope string includes inbox:read:messages and inbox:write:events, and that exp has not passed.

Do Inbox and Toasts need separate tokens?

They read the same feed, so one signIn with the same JWT and scopes covers both.

I'm on an older inbox SDK with a different auth setup.

Older SDK versions used a different authentication method. To move to JWT, see the .

Get started

Quickstarts

Inbox

Toasts

Preferences

Web Components

Authenticate users with a JWT

How the JWT flow works

1. Issue a token

Scopes

3. Read the signed-in user

4. Sign out

5. Refresh tokens

EU-hosted workspaces

Troubleshooting

FAQ

​How the JWT flow works

​1. Issue a token

​Scopes

​2. Sign in on the client

​3. Read the signed-in user

​4. Sign out

​5. Refresh tokens

​EU-hosted workspaces

​Troubleshooting

​FAQ

How the JWT flow works

1. Issue a token

Scopes

2. Sign in on the client

3. Read the signed-in user

4. Sign out

5. Refresh tokens

EU-hosted workspaces

Troubleshooting

FAQ