Vercel KMS Claims
KMS lets you control the claims in every token an issuer signs. A grant's claim policy sets KMS-owned claims that the caller cannot override, and an issuer's claims schema validates the final claim set before signing.
A grant policy, whether a project grant or a Connect grant, can define tokenClaims: a fixed set of claims KMS always applies to tokens signed under that grant. When you call signJWT, KMS layers the grant's tokenClaims over your claims, and the grant's values win on conflict. Use this to pin a claim, such as a tenant or role, that the caller must not be able to change.
An issuer can define a claims schema, a JSON Schema (draft-07) that every token the issuer signs must satisfy. You set it when you create or update the issuer. Before signing, KMS validates the resolved claims against the schema and rejects any token whose claims do not conform.
{
"type": "object",
"required": ["sub", "role"],
"properties": {
"role": { "enum": ["reader", "admin"] }
}
}A claim the schema names, under properties or required (including the allOf, anyOf, oneOf, if, then, else, and not keywords), is protected. KMS drops any caller-supplied value for a protected claim before merging, so a protected claim can only come from the matched grant's tokenClaims. If the schema requires a protected claim that no grant supplies, signing fails validation. This guarantees a protected claim's value comes from the grant, not the caller. In the example above, sub and role are protected, so role must be supplied by the grant.
KMS validates and compiles a claims schema when you set it, and rejects an invalid schema with a 400 response. A schema is bounded so it stays cheap to run on the signing path:
| Constraint | Limit |
|---|---|
| Maximum size | 16 KB |
| Maximum nesting depth | 12 |
Regex- and format-based keywords (pattern, patternProperties, format) and schema references ($ref, $recursiveRef, $dynamicRef) are not allowed.
KMS sets the iat, nbf, and exp claims during signing. They are not part of schema validation, so you do not need to declare them in your claims schema.
When a grant defines tokenClaims, or an issuer defines a claims schema, KMS disables raw message signing for that issuer and you must use signJWT. A raw message could carry a hand-crafted payload that bypasses the claim policy or schema, so KMS denies it by default.
Was this helpful?