Custom Claims
Attach arbitrary key-value metadata to any end user. Claims are baked into the JWT on the next token issue, so your app can read them with a single decode — zero extra API calls, zero latency.
When to use claims
→
User types
Separate student from instructor
→
Feature flags
Per-user toggles like betaAccess: true
→
Team assignment
Department, team, or tenant identifiers
→
App-specific data
Any metadata you want available in the token
How it works
1
Set claims via API
Call POST /api/platform/claims with the user identifier and claims object
2
Claims are merged
New claims merge with existing ones — no need to send the full object every time
3
Claims appear in the JWT
On the next token issue, claims are embedded under custom_claims
set-claims.tstypescript
// Set claims from your backend
await fetch("https://astapa.com/api/platform/claims", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: process.env.CLIENT_ID,
client_secret: process.env.CLIENT_SECRET,
email: "user@example.com",
claims: {
userType: "instructor",
department: "engineering",
betaAccess: true,
},
}),
});Reading claims from the JWT
After setting claims, the user's next JWT includes them. No SDK needed — just decode the token.
read-claims.tstypescript
import jwt from "jsonwebtoken";
const decoded = jwt.verify(accessToken, publicKey, {
algorithms: ["RS256"],
});
decoded.custom_claims.userType // "instructor"
decoded.custom_claims.department // "engineering"
decoded.custom_claims.betaAccess // true
decoded.plan // "pro" (subscription tier)
decoded.role // "owner" (project role)When do claims update?
Claims are embedded at token issue time. If you update claims, the user's current token still has the old values until it expires or they refresh. For immediate effect, revoke the user's tokens to force a re-login.
Supported value types
| Type | Example |
|---|---|
| String | "instructor" |
| Number | 42 |
| Boolean | true |
| String array | ["admin", "editor"] |
4KB limit
Total claims payload (JSON-serialized) must be under 4KB. Keep claims lean — store large data in your own database and reference it by ID.