About Kinde workflows

A workflow is code you own, triggered by Kinde, that shapes tokens, auth steps, and integrations that Kinde doesn’t support out of the box.

How it works:

1. Develop code in your own repo.
2. Connect and sync the repo to Kinde.
3. Kinde executes the code based on triggers.

When to use

Link to this section

• You want Kinde to do something that it doesn’t currently do.
• You want to customize access or ID tokens in ways that we don’t support out of the box. For example, fetch data from an external system and include it as claims in your tokens.
• You want to reduce the size of tokens by removing claims you don’t need.
• You want to change the data type of a claim. For example, changing an array to a space-delimited string.

Example workflow

Link to this section

The following workflow removes the permissions and feature_flags claims from the access token. See the full workflow example: Customize token with workflow.

Sample workflow: Workflow.ts

import {
  onUserTokenGeneratedEvent,
  WorkflowSettings,
  WorkflowTrigger,
  accessTokenCustomClaims,
} from "@kinde/infrastructure";

// The setting for this workflow
export const workflowSettings: WorkflowSettings = {
  id: "removeClaimWorkflow",
  name: "Remove Claim Workflow",
  trigger: WorkflowTrigger.UserTokenGeneration,
  failurePolicy: {
    action: "stop",
  },
  bindings: {
    "kinde.accessToken": {}, // required to modify access token claims
    url: {}, // required for URL parameters
  },
};

// The workflow code to be executed when the event is triggered
export default async function Workflow(event: onUserTokenGeneratedEvent) {
  const accessToken = accessTokenCustomClaims<{
    permissions: string[],
    feature_flags: Record<string, unknown>,
  }>()

  accessToken.permissions = []
  accessToken.feature_flags = {}
}

Kinde workflows

Link to this section

Triggers

Link to this section

• User token generation — Customize access and ID tokens with claims from your own systems.
• User post-authentication — Run logic after sign-in, such as syncing users to external tools or applying security checks.
• User pre-registration — Gate who can create an account before a user record is created in Kinde.
• Pre-MFA — Control when multi-factor authentication is required, including grace periods and conditional enforcement.
• M2M token generation — Customize machine-to-machine tokens for API and service-to-service access.
• New password provided — Enforce custom password rules or sync new passwords to an external system.
• Existing password provided — Validate passwords against an external source, useful for migrations and legacy auth.
• Plan selection — Validate or control subscription plan changes in the self-serve portal or via API.
• Plan cancellation request — Intercept cancellation requests to apply custom eligibility checks or retention logic.

We’ll add more triggers over time, including the option to create your own.

Basic rules

Link to this section

• Workflow code must be written in TypeScript or plain JavaScript.
• Filenames must end in the word Workflow for Kinde to recognize them as containing workflow code. For example, MFAWorkflow.ts or PreauthorizationWorkflow.jsx.
• File extensions must be .ts, .js, .tsx, or .jsx.
• Each trigger can only have one workflow.
• Only Kinde-defined triggers are available for now.

Limitations

Link to this section

• Workflows cannot prevent or bypass Kinde’s built-in verification (for example, email verification or OTP delivery). Those steps always run as part of the auth flow.
• Workflows cannot expose the authentication token (or verification code) for use in your own custom emails. Tokens and codes are only available within Kinde’s secure flow; use custom email content and custom sender to brand the emails Kinde sends.

See more

Link to this section

• Kinde Infrastructure repo on GitHub
• Kinde workflow base template on GitHub

Next steps

Link to this section

• Workflow Quickstart guide
• Workflow tutorials (customize tokens)