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).
| Claim | Type | Present |
|---|---|---|
sub | string | Always — the Customer id |
projectId | string | Always |
sid | string | Always — the session id, for targeted revocation |
roles | string[] | 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, exp | number | Always (standard Unix timestamps) |
Option 1 — Local verification (JWKS)
The recommended default: no network call, so no latency added to your requests.
npm install joseimport { 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/verifyand.well-known/jwks.json.