Mailmus
Auth

Verify sessions in your backend

Short-lived EdDSA-signed JWTs — local verification (JWKS) or server introspection, two approaches with different trade-offs.

The browser and mobile SDKs authenticate your Customers directly against Mailmus. Your own backend (Express, NestJS, Fastify, and so on) then receives the accessToken on every request (Authorization: Bearer ...) and has to verify it — two ways to do that, with a real trade-off between them.

What the token contains

The access token is a JWT signed with EdDSA (Ed25519, one key pair per project), short-lived (accessTokenTtlSeconds, 900s / 15 min by default — configurable under Auth → Settings).

ClaimTypePresent
substringAlways — the Customer id
projectIdstringAlways
sidstringAlways — the session id, for targeted revocation
rolesstring[]Always
act{ sub, email }Only when a member of your team is signed in as this user from the dashboard (see Sign in as a user)
iat, expnumberAlways (standard Unix timestamps)

Option 1 — Local verification (JWKS)

The recommended default: no network call, so no latency added to your requests.

npm install jose
import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
  new URL(`https://api.mailmus.app/projects/${projectId}/.well-known/jwks.json`),
);

const { payload } = await jwtVerify(accessToken, JWKS);
// payload.sub = customerId, payload.projectId, payload.sid, payload.roles, ...

createRemoteJWKSet caches the keys for you — no network call after the first token verified (except on a key rotation, handled through the kid in the JWT header).

Example — NestJS guard

import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from "@nestjs/common";
import { createRemoteJWKSet, jwtVerify } from "jose";

const PROJECT_ID = process.env.MAILMUS_PROJECT_ID!;
const JWKS = createRemoteJWKSet(
  new URL(`https://api.mailmus.app/projects/${PROJECT_ID}/.well-known/jwks.json`),
);

@Injectable()
export class MailmusAuthGuard implements CanActivate {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = request.headers.authorization?.replace("Bearer ", "");
    if (!token) throw new UnauthorizedException();

    try {
      const { payload } = await jwtVerify(token, JWKS);
      request.customer = { id: payload.sub, roles: payload.roles };
      return true;
    } catch {
      throw new UnauthorizedException("Invalid or expired token");
    }
  }
}

One limit to know about: local verification cannot tell that a user has just been banned or that a session has been revoked (auth.sessions.revoke(), a ban, a password reset) — the token stays valid until it expires naturally (15 minutes by default). For most routes, that is an acceptable trade-off. For a sensitive action where a revocation has to cut access immediately, use option 2.

Option 2 — Server introspection

One network call to Mailmus per request, but it reflects the real state right now: session revocation, bans, everything is checked on the Mailmus side before answering.

import { SDK } from "mailmus";

const mailmus = new SDK({ bearer: process.env.MAILMUS_SECRET_KEY });

const customer = await mailmus.customerVerification.customerVerifyVerify({
  projectId: "proj_xxx",
  body: { accessToken },
});
// { id, email, metadata, sessionId, ... }

It uses your secret key (never the publishable one) — call it from your backend only, never from a client.

Which one to pick

  • By default: local verification (JWKS) — fast, and no per-request dependency on Mailmus being reachable.
  • For an irreversible or sensitive action (a payment, deleting an account, access to critical data) right after a possible ban or revocation: server introspection, so you leave no 15-minute window where a revoked token still works.

Nothing stops you from combining the two: local JWKS for most routes, targeted introspection on the most sensitive endpoints.

Next

  • Sessions — list and revoke a user's sessions.
  • API Reference — auth/verify and .well-known/jwks.json.

On this page