Workflow quickstart guide

Follow this guide to set up your project and create your first workflow.

What you need

Link to this section

• A Kinde account with an application set up (sign up for free)
• A GitHub account to host your code (sign up for free)

Quickstart (using the base template)

Link to this section

1. Clone the base template

Link to this section

1. Sign in to your GitHub account and open the Kinde base workflow template.
2. Select the green Use this template button, then select Create a new repository.
3. Enter an easily identifiable name for your repository (for example, kinde-wf-base-template).
4. Clone the repository to your local machine using your preferred method (for example, Git CLI or GitHub Desktop).

The base template contains a basic workflow that writes Hello world to runtime logs when a user authenticates.

2. Connect Git repo to Kinde

Link to this section

1. Sign in to your Kinde account and go to Settings > Environment > Git repo.

2. Select Connect GitHub.

3. Follow the instructions to connect your GitHub account to Kinde.

4. Select the repository you created in the previous step, then select Next.

5. Select the branch (for example, main) and select Save.

   Kinde will automatically sync the code and create a new workflow for you.

6. Go to Kinde home > Workflows to view your new workflow. You should see a new workflow called Workflow 1.

   

7. Select the workflow to see the details and deployments.

8. Select Runtime logs to view the logs for the workflow. This should currently be empty.

3. Test the workflow

Link to this section

Run your Kinde application and sign in. This triggers the workflow and creates a new runtime log entry.

1. Open Runtime logs for the workflow again (refresh the page if the list does not update).

2. Select the new log entry to see Hello world in the output (see sample below).

   Workflow sample output

   Post-authentication trigger fired
   Workflow found
   JavaScript execution started…
   Info Hello world
   🎉 Workflow completed in 0.7ms

Manually create a workflow

Link to this section

Prefer to scaffold the project yourself instead of using the template? Follow these steps to recreate the same base template setup from scratch.

1. Create the project and folder structure

Link to this section

1. Create a new directory for your workflows repository and move into it:

   mkdir kinde-workflows && cd kinde-workflows

2. Initialize a Git repository (skip this if you already have one):

   git init

3. Create the folder structure Kinde expects, including a folder for this workflow:

   Kinde workflow folder structure

   kindeSrc/
     └── environment/
       └── workflows/
         └── postUserAuthentication/

   mkdir -p kindeSrc/environment/workflows/postUserAuthentication

2. Add configuration files

Link to this section

1. Create kinde.json in the project root. This tells Kinde where to discover your workflow code:

   cat > kinde.json << 'EOF'
   {
     "rootDir": "kindeSrc",
     "version": "2025-11-11",
     "integrations": { "npm": { "enabled": true } }
   }
   EOF

2. Initialize a package.json file:

   npm init -y

3. (Optional) Add the Kinde infrastructure package if you want workflow types and methods during development:

   npm i @kinde/infrastructure

4. (Optional) Add a tsconfig.json if you use TypeScript:

   cat > tsconfig.json << 'EOF'
   {
     "compilerOptions": {
       "target": "ES2020",
       "module": "ESNext",
       "moduleResolution": "Node",
       "strict": true,
       "esModuleInterop": true,
       "skipLibCheck": true
     },
     "include": ["**/*.ts"]
   }
   EOF

3. Create the workflow file

Link to this section

1. Create a workflow file. The filename must end with Workflow (for example, Workflow.ts or postAuthWorkflow.ts). See Workflow files.

   touch kindeSrc/environment/workflows/postUserAuthentication/Workflow.ts

2. Add the following code. This matches the base template: it runs on the post-authentication trigger and logs Hello world.

   kindeSrc/environment/workflows/postUserAuthentication/Workflow.ts

   import {
     onPostAuthenticationEvent,
     WorkflowSettings,
     WorkflowTrigger,
   } from "@kinde/infrastructure";
   
   // The setting for this workflow
   export const workflowSettings: WorkflowSettings = {
     id: "onPostUserAuthentication",
     name: "Post user authentication workflow",
     trigger: WorkflowTrigger.PostAuthentication,
   };
   
   // The workflow code to be executed when the event is triggered
   export default async function Workflow(event: onPostAuthenticationEvent) {
     console.log("Hello world");
   }

3. Commit your changes and push them to a GitHub repository.

   git add .
   git commit -m "Initial kinde workflow commit"
   git push

   You must have a GitHub repository and a remote origin set before you can push. See GitHub’s guide on adding locally hosted code to GitHub.

4. Connect Git repo to Kinde

Link to this section

Follow step 2 in Quickstart to connect your repository and confirm the workflow appears under Workflows.

5. Test the workflow

Link to this section

Follow step 3 in Quickstart: sign in to your app, then check Runtime logs for the Hello world output.

Next steps

Link to this section

You have created your first Kinde workflow. Modify it to fit your needs, or add more workflows. Practical examples:

• Customize access tokens with a workflow
• Create custom password validation with a workflow
• Browse other tutorials in the workflow tutorials section
• Explore more examples in the Kinde workflow examples GitHub repository