Token & JWKS Reference

A reference for the access tokens vuer-auth issues, the claims they carry, and the JWKS endpoints used to verify them.

Environments

Environment	Base URL
Staging	`https://staging-auth.vuer.ai`
Production	`https://auth.vuer.ai`

The issuer (iss) of a token is the base URL of the server that issued it.

Signing algorithm

Tokens are JWTs signed with EdDSA (Ed25519).

Algorithm header: alg: "EdDSA"
Faster signing and smaller signatures than RS256.
Always pin algorithms: ["EdDSA"] when verifying — never accept alg: none or an unexpected algorithm.

Claims

A decoded access token looks like:

{
  "sub": "user-id",              // stable user id — use this as your primary key
  "email": "user@example.com",
  "name": "Jane Doe",
  "username": "jane",
  "email_verified": true,
  "iss": "https://auth.vuer.ai", // issuer = the server base URL
  "aud": "your-client-id",       // audience = the clientId the token was issued for
  "iat": 1710000000,             // issued-at (seconds)
  "exp": 1710604800              // expiry (seconds) — default lifetime is 7 days
}

Claim	Meaning
`sub`	Stable user identifier. Prefer this over `email` (emails change).
`email`, `email_verified`	User email and whether it's verified.
`name`, `username`	Display name and username.
`iss`	Issuer — the base URL of the auth server.
`aud`	The `clientId` the token was issued for (see Register an App).
`iat`, `exp`	Issued-at and expiry, in seconds. Default lifetime is 7 days.

JWKS endpoints

The public signing keys are published as a JSON Web Key Set:

Path	Notes
`GET /.well-known/jwks.json`	Recommended — the standard, issuer-advertised location.
`GET /api/auth/jwks`	Compatible alternative; serves the same keys.

A JWKS response looks like:

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "alg": "EdDSA",
      "use": "sig",
      "kid": "…",
      "x": "…"           // public key material
    }
  ]
}

Tip: Use createRemoteJWKSet(new URL("…/.well-known/jwks.json")) so the keys are fetched, cached, and automatically refreshed on rotation. Create it once at module scope.

Verifying

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://staging-auth.vuer.ai/.well-known/jwks.json"),
);

const { payload } = await jwtVerify(token, JWKS, {
  algorithms: ["EdDSA"],
  // issuer: "https://staging-auth.vuer.ai", // optional
  // audience: "your-client-id",             // optional
});