---
title: Vercel KMS Claims
product: vercel
url: /docs/kms/concepts/claims
canonical_url: "https://vercel.com/docs/kms/concepts/claims"
last_updated: 2018-10-20
type: conceptual
prerequisites:
  - /docs/kms/concepts
  - /docs/kms
related:
  - /docs/kms/concepts/project-grants
  - /docs/kms/concepts/connect-grants
  - /docs/kms/ts-sdk-reference
summary: How a KMS grant sets KMS-owned token claims the caller cannot override, and how an issuer claims schema validates every token it signs.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# 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.

## Claim policies

A grant policy, whether a [project grant](/docs/kms/concepts/project-grants) or a [Connect grant](/docs/kms/concepts/connect-grants), can define `tokenClaims`: a fixed set of claims KMS always applies to tokens signed under that grant. When you call `signToken`, 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.

## Claims schema

An issuer can define a claims schema, a [JSON Schema](https://json-schema.org/) (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.

```json filename="claims-schema.json"
{
  "type": "object",
  "required": ["sub", "role"],
  "properties": {
    "role": { "enum": ["reader", "admin"] }
  }
}
```

### Protected claims

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.

### Schema constraints

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.

### Reserved time claims

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.

## Message signing is disabled

When a grant defines `tokenClaims`, or an issuer defines a claims schema, KMS disables raw message signing for that issuer and you must use `signToken`. A raw message could carry a hand-crafted payload that bypasses the claim policy or schema, so KMS denies it by default.

## Related

- [Project grants](/docs/kms/concepts/project-grants)
- [Connect grants](/docs/kms/concepts/connect-grants)
- [SDK Reference](/docs/kms/ts-sdk-reference)


---

[View full sitemap](/docs/sitemap)