Pass application context to an API
A backend API needs a tenant or entitlement value in each access token.
Kinde · Const
Custom claims
Custom claims let Kinde workflows add application-specific data to access or ID tokens. They can also be supplied through public properties or token customization.
How it works
Custom claims add application-specific information to Kinde-issued access or ID tokens. Workflows can set claims programmatically, while token customization can include supported claims and properties; standard protected claims remain read-only.
Syntax
setCustomClaim(name: string, value: any): voidParameters
| Name | Type | Description |
|---|---|---|
name | string | The claim key to add or update. |
value | any | The value assigned to the claim. |
Returns
setCustomClaim(name: string, value: any): void; the claim is available in the token returned to the client.
Key points
- Claims assigned during token generation become part of the access token delivered to the client.
- The infrastructure helper supports typed claim objects, reducing mistakes when setting workflow values.
- The low-level setCustomClaim method accepts a claim name and its value.
- Kinde properties provide another route for representing custom data as claims.
- A property must be public rather than private to be eligible for token inclusion.
Example: Add a custom access-token claim
import {
accessTokenCustomClaims,
onUserTokenGeneratedEvent,
} from "@kinde/infrastructure";
export default async function workflow(event: onUserTokenGeneratedEvent) {
const accessToken = accessTokenCustomClaims<{ companyName: string }>();
accessToken.companyName = "Acme Inc.";
}This workflow adds a typed companyName claim to the user's access token before Kinde returns it.
When to use it
Customize identity-token data
An application needs identity data in an ID token.
Expose public properties as claims
A service stores account attributes in Kinde properties.
Interview questions
QWhat is a custom claim in Kinde?
A custom claim is application-specific data added to a Kinde access or ID token. It can be created through token customization or by assigning values in a token-generation workflow.
Follow-up: How would you add data fetched from another system? Use a user-token-generation workflow, call the external service, and assign the resulting value to the appropriate token claim.
QHow do you add a custom claim to an access token?
Use accessTokenCustomClaims with a TypeScript type, then assign the claim property in the workflow. Kinde includes that value in the access token returned to the client.
Follow-up: What must be added when using the lower-level API? Use the kinde.accessToken binding and call setCustomClaim(name, value).
QWhich claims cannot be modified?
Standard claims that Kinde protects cannot be changed. Examples include sub, aud, exp, iat, iss, nbf, and sid; access tokens also prohibit jti.
Follow-up: How can preset claims or properties be included without workflow code? Configure Token customization for the relevant application and token type, then select the desired claims or properties.
Related
Custom claims and data with propertiesToken customizationkinde.accessTokenUser token generation workflowaccessTokenCustomClaimskinde.idToken