NextJS App Router SDK

This SDK is for NextJS version 13+ and uses Server Side Components and App Router.

New to Kinde? Get started here

If you’re using version 1 see Next.js App Router V1

If you’re using the pages router see NextJS Pages Router

Install for a new project

Link to this section

The easiest way to get started is to use the NextJS starter kit, and watch a demo video.

Install for an existing project

Link to this section

npm i @kinde-oss/kinde-auth-nextjs
yarn add @kinde-oss/kinde-auth-nextjs
pnpm i @kinde-oss/kinde-auth-nextjs

Set callback URLs

Link to this section

1. In Kinde, go to Settings > Applications > [Your app] > View details.
2. Add your callback URLs in the relevant fields. For example:
   • Allowed callback URLs (also known as redirect URIs) - for example http://localhost:3000/api/auth/kinde_callback
   • Allowed logout redirect URLs - for example http://localhost:3000
3. Select Save.

Configure environment variables

Link to this section

Put these variables in a .env.local file in the root of your Next.js app. You can find these variables on your Kinde Settings > Applications > [Your app] > View details page.

• KINDE_CLIENT_ID - Your business’s unique ID on Kinde
• KINDE_CLIENT_SECRET - Your business’s secret key (do not share)
• KINDE_ISSUER_URL - your kinde domain
• KINDE_SITE_URL - where your app is running
• KINDE_POST_LOGOUT_REDIRECT_URL - where you want users to be redirected to after logging out. Make sure this URL is under your allowed logout redirect URLs.
• KINDE_POST_LOGIN_REDIRECT_URL - where you want users to be redirected to after authenticating.
• KINDE_AUDIENCE - optional - a whitespace separated list of audiences to populate the aud claim in the token.

Replace the information in the example with your own information. You might also set different URLs depending where your project is running. They need to match the callback URLs you entered in Kinde, above.

KINDE_CLIENT_ID=<your_kinde_client_id>
KINDE_CLIENT_SECRET=<your_kinde_client_secret>
KINDE_ISSUER_URL=https://<your_kinde_subdomain>.kinde.com
KINDE_SITE_URL=http://localhost:3000
KINDE_POST_LOGOUT_REDIRECT_URL=http://localhost:3000
KINDE_POST_LOGIN_REDIRECT_URL=http://localhost:3000/dashboard

Set up Kinde Auth Route Handlers

Link to this section

Create the following file app/api/auth/[kindeAuth]/route.js inside your Next.js project. Inside the file route.js put this code:

import {handleAuth} from "@kinde-oss/kinde-auth-nextjs/server";
export const GET = handleAuth();

This will handle Kinde Auth endpoints in your Next.js app.

Important! Our SDK relies on this file existing in this location specified above.

Authentication

Link to this section

Sign up and sign in

Link to this section

The SDK ships with <LoginLink> and <RegisterLink> components which can be used to start the auth flow.

import {RegisterLink, LoginLink} from "@kinde-oss/kinde-auth-nextjs/components";

...

<LoginLink>Sign in</LoginLink>
<RegisterLink>Sign up</RegisterLink>

Redirecting after authentication

Link to this section

Static redirect

If you want to redirect users to a certain page after logging in, you can set the KINDE_POST_LOGIN_REDIRECT_URL environment variable in your .env.local file.

Dynamic redirect

You can also set a postLoginRedirectURL parameter to tell us where to redirect after authenticating.

import {RegisterLink, LoginLink} from "@kinde-oss/kinde-auth-nextjs/components";

...

<LoginLink postLoginRedirectURL="/dashboard">Sign in</LoginLink>
<RegisterLink postLoginRedirectURL="/welcome">Sign up</RegisterLink>

This appends post_login_redirect_url to the search params when redirecting to Kinde Auth. You can achieve the same result as above, like this:

import { redirect } from "next/navigation";
...

redirect('/api/auth/login?post_login_redirect_url=/dashboard')

...

Logout

Link to this section

This is implemented in much the same way as signing up or signing in. A component is provided for you.

import {LogoutLink} from "@kinde-oss/kinde-auth-nextjs/components";

...

<LogoutLink>Log out</LogoutLink>

Kinde Auth data - Server

Link to this section

You can get an authorized user’s Kinde Auth data from any server component using the getKindeServerSession helper.

Method	Description
isAuthenticated	Check if the user is authenticated
getUser	Get the current user’s details
getOrganization	Get the current user’s organization
getUserOrganizations	Get all the organizations the current user belongs to
getPermission	Check if the current user has a permission
getPermissions	Get the current user’s permissions
getFlag	Get a feature flag
getBooleanFlag	Get a boolean feature flag
getIntegerFlag	Get an integer feature flag
getStringFlag	Get a string feature flag
refreshTokens	Refresh tokens to get up-to-date Kinde data
getAccessToken	Get the decoded access token
getAccessTokenRaw	Get the access token
getIdToken	Get the decoded ID token
getIdTokenRaw	Get the ID token
getClaim	Get a claim from either token

isAuthenticated

Link to this section

Check if the user is authenticated.

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {isAuthenticated} = getKindeServerSession();
const isUserAuthenticated = await isAuthenticated();

Returns

Link to this section

true;

getUser

Link to this section

Get the logged in user’s details.

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getUser} = getKindeServerSession();
const user = await getUser();

console.log(user);

Returns

Link to this section

{
  "id": "kp_123",
  "email": "example@email.com",
  "family_name": "Example",
  "given_name": "User",
  "picture": null,
  "username": "ExampleUsername",
  "phone_number": "1234567890",
  "properties": {
    "usr_city": "",
    "usr_industry": "",
    "usr_job_title": "",
    "usr_middle_name": "",
    "usr_postcode": "",
    "usr_salutation": "",
    "usr_state_region": "",
    "usr_street_address": "",
    "usr_street_address_2": ""
  }
}

getOrganization

Link to this section

Get the current user’s organization

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getOrganization} = getKindeServerSession();
const org = await getOrganization();

console.log(org);

Returns

Link to this section

{
  "orgCode": "org_123",
  "orgName": "Deafault Org",
  "properties": {
    "org_city": "",
    "org_country": "",
    "org_industry": "",
    "org_postcode": "",
    "org_state_region": "",
    "org_street_address": "",
    "org_street_address_2": ""
  }
}

getUserOrganizations

Link to this section

Get all the organizations the current user belongs to

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getUserOrganizations} = getKindeServerSession();
const userOrgs = await getUserOrganizations();

console.log(userOrgs);

Returns

Link to this section

{
  "orgCodes": ["org_123", "org_456"],
  "orgs": [
    {
      "code": "org_123",
      "name": "Deafault Org"
    },
    {
      "code": "org_456",
      "name": "Another Org"
    }
  ]
}

getPermission

Link to this section

Check if the current user has a permission.

Parameter	Type	Description
code	string	The permission code to check

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getPermission} = getKindeServerSession();
const canEatTacos = await getPermission("eat:tacos");

console.log(canEatTacos);

Returns

Link to this section

{
  "isGranted": true,
  "orgCode": "org_123"
}

getPermissions

Link to this section

Get the current user’s permissions.

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getPermissions} = getKindeServerSession();
const permissions = await getPermissions();

console.log(permissions);

Returns

Link to this section

{
  "permissions": ["eat:tacos", "read:books"],
  "orgCode": "org_123"
}

getFlag

Link to this section

Get a feature flag

Parameter	Type	Description
code	string	The flag code to check
defaultValue	boolean | string | number	The default value to return if the flag is not set
type	enum (b | s | i)	The type of the flag

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getFlag} = getKindeServerSession();
const billingFlag = await getFlag("billing", false, "b");

console.log(billingFlag);

Returns

Link to this section

{
  "code": "billing",
  "type": "boolean",
  "value": true,
  "defaultValue": false,
  "is_default": false
}

getBooleanFlag

Link to this section

Get a boolean feature flag

Parameter	Type	Description
code	string	The flag code to check
defaultValue	boolean	The default value to return if the flag is not set

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getBooleanFlag} = getKindeServerSession();
const billingFlag = await getBooleanFlag("billing", false);

console.log(billingFlag);

Returns

Link to this section

true;

getIntegerFlag

Link to this section

Get a boolean feature flag

Parameter	Type	Description
code	string	The flag code to check
defaultValue	boolean	The default value to return if the flag is not set

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getIntegerFlag} = getKindeServerSession();
const billingVersion = await getIntegerFlag("billingVersion", 0);

console.log(billingVersion);

Returns

Link to this section

2

getStringFlag

Link to this section

Get a string feature flag

Parameter	Type	Description
code	string	The flag code to check
defaultValue	string	The default value to return if the flag is not set

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getStringFlag} = getKindeServerSession();
const theme = await getStringFlag("theme", "system");

console.log(theme);

Returns

Link to this section

"light"

refreshTokens

Link to this section

Refresh tokens to get up-to-date Kinde data

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";
import {someUpdateFunction} from "@/app/actions";

const {refreshTokens} = getKindeSeverSession();
await someUpdateFunction({
  param_1: "value_1",
  param_2: "value_2"
});
await refreshTokens();

getAccessToken

Link to this section

Get the decoded access token

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getAccessToken} = getKindeSeverSesion();
const accessToken = await getAccessToken();

console.log(accessToken);

Returns

Link to this section

{
  "aud": ["your-api"],
  "azp": 1234567890,
  "email": "example@email.com",
  "exp": 1234567890,
  "feature_flags": {
    "isonboardingcomplete": {
      "t": "b",
      "v": false
    }
  },
  "iat": 1234567890,
  "iss": "https://your-kinde-subdomain.kinde.com",
  "jti": "7802e2d2-asdf-431e-bc72-5ed95asdf475d",
  "org_code": "org_123",
  "org_name": "Default Org",
  "organization_properties": {
    "kp_org_city": {}
  },
  "permissions": ["create:template"],
  "roles": [
    {
      "id": "018ee9aa-f92b-83fc-1d40-1234567890",
      "key": "admin",
      "name": "Admin"
    }
  ],
  "scp": ["openid", "profile", "email", "offline"],
  "sub": "kp_6123456789009876",
  "user_properties": {
    "kp_usr_city": {}
  }
}

getAccessTokenRaw

Link to this section

Get the access token

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getAccessTokenRaw} = getKindeSeverSesion();
const accessToken = await getAccessTokenRaw();

console.log(accessToken);

Returns

Link to this section

eyJhxxx.eyJhdxxx.A4djjxxx

getIdToken

Link to this section

Get the decoded ID token

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getIdToken} = getKindeSeverSesion();
const idToken = await getIdToken();

console.log(idToken);

Returns

Link to this section

{
  "at_hash": "ZY6jx1SGjzgkHGJ_2Jabcd",
  "aud": ["feb8e697b967466eacb96d26c5ca0e12"],
  "auth_time": 1234567890,
  "azp": "feb8e099xxx",
  "email": "example@email.com",
  "email_verified": true,
  "exp": 123456789,
  "ext_provider": {
    "claims": {
      "connection_id": "bcc486xxx",
      "email": "example@email.com",
      "family_name": "User",
      "given_name": "Example",
      "is_confirmed": true,
      "picture": "https://lh3.googleusercontent.com/a/ACgxxx",
      "profile": {
        "email": "example@email.com",
        "family_name": "User",
        "given_name": "Example",
        "id": "1234567890",
        "name": "Example user",
        "picture": "https://lh3.googleusercontent.com/a/ACgxxx",
        "verified_email": true
      }
    },
    "connection_id": "bccxxx",
    "name": "Google"
  },
  "family_name": "User",
  "given_name": "Example",
  "iat": 1234567890,
  "iss": "https://your-kinde-subdomain.kinde.com",
  "jti": "e7e18303-0ea5-402d-932c-xxx",
  "name": "Example user",
  "org_codes": ["org_123"],
  "organizations": [
    {
      "id": "org_123",
      "name": "Default Organization"
    }
  ],
  "picture": "https://lh3.googleusercontent.com/a/ACgxxx",
  "rat": 1234567890,
  "sub": "kp_1234567890",
  "updated_at": 1234567890,
  "user_properties": {
    "kp_usr_city": {}
  }
}

getIdTokenRaw

Link to this section

Get the ID token

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getIdTokenRaw} = getKindeSeverSesion();
const idToken = await getIdTokenRaw();

console.log(idToken);

Returns

Link to this section

eyJhxxx.eyJhdxxx.A4djjxxx

getClaim

Link to this section

Get a claim from either token

Parameter	Type	Description
claim	string	The claim key
type	enum (access_token | id_token)	The token to get the claim from

Example

Link to this section

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";

const {getClaim} = getKindeSeverSesion();
const username = await getClaim("preferred_username", "id_token");

console.log(idToken);

Returns

Link to this section

"exampleUsername"

Kinde Auth data - Client

Link to this section

You can get an authorized user’s Kinde Auth data from any client component using the useKindeBrowser helper.

Variable / Method	Description
isAuthenticated	Get a feature flag
user / getUser	The current in user’s details
organization / getOrganization	The current user’s organization
userOrganizations / getUserOrganizations	All the organizations the current user belongs to
getPermission	Check if the current user has a permission
permissions / getPermissions	The current user’s permissions
getFlag	Get the access token
getBooleanFlag	Get the access token
getIntegerFlag	Get the access token
getStringFlag	Get the access token
refreshData	Refresh tokens to get up-to-date Kinde data
accessToken / getAccessToken	Check if the user is authenticated
accessTokenRaw / getAccessTokenRaw	Get the current user’s details
idToken / getIdToken	Get all the organizations the current user belongs to
idTokenRaw / getIdTokenRaw	Check if the current user has a permission
isLoading	Is Kinde data loading
error	Error message if there is an error

Tip: Use isLoading to ensure the data is up to date. You can return a loading spinner or something similar if you want.

isAuthenticated

Link to this section

Check if the user is authenticated.

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {isAuthenticated} = useKindeBrowserClient();
console.log(isAuthenticated);

Returns

Link to this section

true;

user / getUser

Link to this section

Get the logged in user’s details.

Example

Link to this section

"use client";

import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {user, getUser} = useKindeBrowserClient();
const alsoUser = getUser();

console.log(user);

Returns

Link to this section

{
  "id": "kp_123",
  "email": "example@email.com",
  "family_name": "Example",
  "given_name": "User",
  "picture": null,
  "username": "ExampleUsername",
  "phone_number": "1234567890",
  "properties": {
    "usr_city": "",
    "usr_industry": "",
    "usr_job_title": "",
    "usr_middle_name": "",
    "usr_postcode": "",
    "usr_salutation": "",
    "usr_state_region": "",
    "usr_street_address": "",
    "usr_street_address_2": ""
  }
}

organization / getOrganization

Link to this section

Get the current user’s organization

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {organization, getOrganization} = useKindeBrowserClient();
const org = getOrganization();

console.log(organization, org);

Returns

Link to this section

{
  "orgCode": "org_123",
  "orgName": "Deafault Org",
  "properties": {
    "org_city": "",
    "org_country": "",
    "org_industry": "",
    "org_postcode": "",
    "org_state_region": "",
    "org_street_address": "",
    "org_street_address_2": ""
  }
}

userOrganizations / getUserOrganizations

Link to this section

Get all the organizations the current user belongs to

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {userOrganizations, getUserOrganizations} = useKindeBrowserClient();
const userOrgs = getUserOrganizations();

console.log(userOrganizations, userOrgs);

Returns

Link to this section

{
  "orgCodes": ["org_123", "org_456"],
  "orgs": [
    {
      "code": "org_123",
      "name": "Deafault Org"
    },
    {
      "code": "org_456",
      "name": "Another Org"
    }
  ]
}

getPermission

Link to this section

Check if the current user has a permission.

Parameter	Type	Description
code	string	The permission code to check

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {getPermission} = useKindeBrowserClient();
const canEatTacos = getPermission("eat:tacos");

console.log(canEatTacos);

Returns

Link to this section

{
  "isGranted": true,
  "orgCode": "org_123"
}

permissions / getPermissions

Link to this section

Get the current user’s permissions.

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {permissions, getPermissions} = useKindeBrowserClient();
const perms = getPermissions();

console.log(permissions, permis);

Returns

Link to this section

{
  "permissions": ["eat:tacos", "read:books"],
  "orgCode": "org_123"
}

getFlag

Link to this section

Get a feature flag

Parameter	Type	Description
code	string	The flag code to check
defaultValue	boolean | string | number	The default value to return if the flag is not set
type	enum (b | s | i)	The type of the flag

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {getFlag} = useKindeBrowserClient();
const billingFlag = getFlag("billing", false, "b");

console.log(billingFlag);

Returns

Link to this section

{
  "code": "billing",
  "type": "boolean",
  "value": true,
  "defaultValue": false,
  "is_default": false
}

getBooleanFlag

Link to this section

Get a boolean feature flag

Parameter	Type	Description
code	string	The flag code to check
defaultValue	boolean	The default value to return if the flag is not set

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {getBooleanFlag} = useKindeBrowserClient();
const billingFlag = getBooleanFlag("billing", false);

console.log(billingFlag);

Returns

Link to this section

true;

getIntegerFlag

Link to this section

Get a boolean feature flag

Parameter	Type	Description
code	string	The flag code to check
defaultValue	boolean	The default value to return if the flag is not set

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {getIntegerFlag} = useKindeBrowserClient();
const billingVersion = getIntegerFlag("billingVersion", 0);

console.log(billingVersion);

Returns

Link to this section

2

getStringFlag

Link to this section

Get a string feature flag

Parameter	Type	Description
code	string	The flag code to check
defaultValue	string	The default value to return if the flag is not set

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {getStringFlag} = useKindeBrowserClient();
const theme = getStringFlag("theme", "system");

console.log(theme);

Returns

Link to this section

"light"

refreshData

Link to this section

Refresh tokens to get up-to-date Kinde data

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";
import {someUpdateFunction} from "@/app/actions";

const {refreshData} = useKindeBrowserClient();

await someUpdateFunction({
  param_1: "value_1",
  param_2: "value_2"
});
await refreshData();

accessToken / getAccessToken

Link to this section

Get the decoded access token

Example

Link to this section

"use client";
import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {accessToken, getAccessToken} = useKindeBrowserClient();
const aTok = getAccessToken();

console.log(accessToken, aTok);

Returns

Link to this section

{
  "aud": ["your-api"],
  "azp": 1234567890,
  "email": "example@email.com",
  "exp": 1234567890,
  "feature_flags": {
    "isonboardingcomplete": {
      "t": "b",
      "v": false
    }
  },
  "iat": 1234567890,
  "iss": "https://your-kinde-subdomain.kinde.com",
  "jti": "7802e2d2-asdf-431e-bc72-5ed95asdf475d",
  "org_code": "org_123",
  "org_name": "Default Org",
  "organization_properties": {
    "kp_org_city": {}
  },
  "permissions": ["create:template"],
  "roles": [
    {
      "id": "018ee9aa-f92b-83fc-1d40-1234567890",
      "key": "admin",
      "name": "Admin"
    }
  ],
  "scp": ["openid", "profile", "email", "offline"],
  "sub": "kp_6123456789009876",
  "user_properties": {
    "kp_usr_city": {}
  }
}

accessTokenRaw / getAccessTokenRaw

Link to this section

Get the access token

Example

Link to this section

import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {accessTokenRaw, getAccessTokenRaw} = useKindeBrowserClient();
const aTokRaw = getAccessTokenRaw();

console.log(accessTokenRaw, aTokRaw);

Returns

Link to this section

eyJhxxx.eyJhdxxx.A4djjxxx

idToken / getIdToken

Link to this section

Get the decoded ID token

Example

Link to this section

import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {idToken, getIdToken} = useKindeBrowserClient();
const idTok = getIdToken();

console.log(idToken, idTok);

Returns

Link to this section

{
  "at_hash": "ZY6jx1SGjzgkHGJ_2Jabcd",
  "aud": ["feb8e697b967466eacb96d26c5ca0e12"],
  "auth_time": 1234567890,
  "azp": "feb8e099xxx",
  "email": "example@email.com",
  "email_verified": true,
  "exp": 123456789,
  "ext_provider": {
    "claims": {
      "connection_id": "bcc486xxx",
      "email": "example@email.com",
      "family_name": "User",
      "given_name": "Example",
      "is_confirmed": true,
      "picture": "https://lh3.googleusercontent.com/a/ACgxxx",
      "profile": {
        "email": "example@email.com",
        "family_name": "User",
        "given_name": "Example",
        "id": "1234567890",
        "name": "Example user",
        "picture": "https://lh3.googleusercontent.com/a/ACgxxx",
        "verified_email": true
      }
    },
    "connection_id": "bccxxx",
    "name": "Google"
  },
  "family_name": "User",
  "given_name": "Example",
  "iat": 1234567890,
  "iss": "https://your-kinde-subdomain.kinde.com",
  "jti": "e7e18303-0ea5-402d-932c-xxx",
  "name": "Example user",
  "org_codes": ["org_123"],
  "organizations": [
    {
      "id": "org_123",
      "name": "Default Organization"
    }
  ],
  "picture": "https://lh3.googleusercontent.com/a/ACgxxx",
  "rat": 1234567890,
  "sub": "kp_1234567890",
  "updated_at": 1234567890,
  "user_properties": {
    "kp_usr_city": {}
  }
}

idTokenRaw / getIdTokenRaw

Link to this section

Get the ID token

Example

Link to this section

import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {idTokenRaw, getIdTokenRaw} = useKindeBrowserClient();
const idTokRaw = getIdTokenRaw();

console.log(idTokenRaw, idTokRaw);

Returns

Link to this section

eyJhxxx.eyJhdxxx.A4djjxxx

isLoading

Link to this section

Is Kinde data loading

Example

Link to this section

import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {user, isLoading} = useKindeBrowserClient();

if (isLoading) return <div>Loading...</div>;

return <div>Hello {user.given_name}</div>;

Returns

Link to this section

true

error

Link to this section

Error message if there is an error

Example

Link to this section

import {useKindeBrowserClient} from "@kinde-oss/kinde-auth-nextjs";

const {user, isLoading, error} = useKindeBrowserClient();

if (isLoading) return <div>Loading...</div>;

if (error) return <div>There was an error</div>;

return <div>Hello {user.given_name}</div>;

Returns

Link to this section

true

Protecting routes

Link to this section

It’s likely that your application will have both pages that are publicly available and private ones which should only be available to logged in users. There are multiple ways you can protect pages with Kinde Auth.

Protect routes with Kinde Auth data

Link to this section

On the page you want to protect, you can check if the user is authenticated and then handle it right then and there by grabbing the Kinde Auth data.

• In Server Components you can get the Kinde Auth data by using the getKindeServerSession helper
• In Client Components you can get the Kinde Auth Data using the useKindeBrowserClient helper

// app/protected/page.tsx - Server Component

import { LoginLink } from "@kinde-oss/kinde-auth-nextjs/components";
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";

export default async function Protected() {
  const { isAuthenticated } = getKindeServerSession();

  return (await isAuthenticated()) ? (
    <div>
      This page is protected - but you can view it because you are authenticated
    </div>
  ) : (
    <div>
      This page is protected, please <LoginLink>Login</LoginLink> to view it
    </div>
  );
}

// app/protected/page.tsx - Client component
"use client";

import { useKindeBrowserClient } from "@kinde-oss/kinde-auth-nextjs";
import { LoginLink } from "@kinde-oss/kinde-auth-nextjs/components";

export default function Admin() {
  const { isAuthenticated, isLoading } = useKindeBrowserClient();

  if (isLoading) return <div>Loading...</div>;

  return isAuthenticated ? (
    <div>Admin content</div>
  ) : (
    <div>
      You have to <LoginLink>Login</LoginLink> to see this page
    </div>
  );
}

In the example above, we show different content based on whether or not the user is authenticated. If you want to automatically send the user to the sign in screen, you can do something like the following:

// app/protected/page.tsx - Server Component

import {getKindeServerSession} from "@kinde-oss/kinde-auth-nextjs/server";
import {redirect} from "next/navigation";

export default async function Protected() {
  const {isAuthenticated} = getKindeServerSession();

  if (!(await isAuthenticated())) {
    redirect("/api/auth/login");
  }

  return <div>Protected content</div>;
}

// app/protected/page.tsx - Client Component

// As of right now, this can't be done in Client Components because of how Next.js handles
// navigation in client components with prefetching and caching.
// But you can still achieve an automatic redirect with middleware

If you want the user to be redirected back to that route after signing in, you can set post_login_redirect_url in the search params of the redirect.

if (!(await isAuthenticated())) {
  redirect("/api/auth/login?post_login_redirect_url=/protected");
}

Protect routes using middleware

Link to this section

You can also protect routes with Next.js middleware.

As of right now the middleware in the app router does not work when trying to redirect to api/auth/login. This is because of Next.js caching which causes issues during authentication.

Default page protection

We provide a withAuth helper that will protect routes covered by the matcher. If the user is not authenticated then they are redirected to login and once they have logged in they will be redirected back to the protected page which they should now have access to.

import {withAuth} from "@kinde-oss/kinde-auth-nextjs/middleware";
export default function middleware(req) {
  return withAuth(req);
}
export const config = {
  matcher: ["/admin"]
};

Page protection with callback function after authorization

You can use the withAuth helper as shown below with a middleware callback function which has access to the req.kindeAuth object that exposes the token and user data.

import {withAuth} from "@kinde-oss/kinde-auth-nextjs/middleware";

export default withAuth(async function middleware(req) {
  console.log("look at me", req.kindeAuth);
});

export const config = {
  matcher: ["/admin"]
};

Middleware options

There are options that can be passed into the middleware function to configure its functionality.

• isReturnToCurrentPage - redirect the user back to the page they were trying to access
• loginPage - define the path of the login page (where the users are redirected to when not authenticated)
• publicPaths - define the public paths
• isAuthorized - define the criteria for authorization

import {withAuth} from "@kinde-oss/kinde-auth-nextjs/middleware";
export default withAuth(
  async function middleware(req) {
    console.log("look at me", req.kindeAuth);
  },
  {
    isReturnToCurrentPage: true,
    loginPage: "/login",
    isAuthorized: ({token}) => {
      // The user will be considered authorized if they have the permission 'eat:chips'
      return token.permissions.includes("eat:chips");
    }
  }
);

export const config = {
  matcher: ["/admin"]
};

Refreshing Kinde data

Link to this section

Kinde data can be updated via the UI or with the Management API. To have these updates be reflected in your app, you will need to get the most up-to-date Kinde data and then refresh the tokens in your session.

To get the most up-to-date Kinde data in your session, use the refreshTokens helper function.

const {refreshTokens} = getKindeServerSession();

const handleRefresh = async () => {
  await refreshTokens();
}

...

<button onClick={handleRefresh}>Get up to date data</button>

Kinde Management API

Link to this section

You need to enable the application’s access to the Kinde Management API. You can do this in Kinde by going to Settings > APIs > Kinde Management API and then toggling on your Next.js application under the Applications tab.

To use our management API please see @kinde/management-api-js

Server Component example:

import { Roles, Users } from "@kinde/management-api-js";

export default async function Dashboard() {
  const { roles } = await Roles.getRoles();
  const { users } = await Users.getUsers();

  return (
    <div className="container">
      <div className="card start-hero">
        <p className="text-body-2 start-hero-intro">Woohoo!</p>
        <p className="text-display-2">
          Your authentication is all sorted.
          <br />
          Build the important stuff.
        </p>
      </div>
      <section className="next-steps-section">
        <h2 className="text-heading-1">Next steps for you</h2>
      </section>

      <pre>{JSON.stringify(users, null, 2)}</pre>
    </div>
  );
}

Route Handler example:

import {NextResponse} from "next/server";
import {Users} from "@kinde/management-api-js";

export async function GET() {
  const {users} = await Users.getUsers();

  return NextResponse.json({users});
}

Organizations

Link to this section

Create organizations

Link to this section

To create an organization from your app, you can use the CreateOrgLink component.

import {CreateOrgLink} from "@kinde-oss/kinde-auth-nextjs/components";

<CreateOrgLink orgName="Hurlstone">Create org</CreateOrgLink>;

Sign into organizations

Link to this section

You can have your users sign into a specific organization by setting the orgCode param in the LoginLink and RegisterLink components.

import {LoginLink, RegisterLink} from "@kinde-oss/kinde-auth-nextjs/components";

<LoginLink orgCode="org_7392cf35a1e">Login</LoginLink>
<RegisterLink orgCode="org_7392cf35a1e">Register</RegisterLink>

If the orgCode is not specified and the user belongs to multiple organizations, they will be prompted to choose which organization to sign into during the login or register flow.

Analytics

Link to this section

UTM tags

Link to this section

UTM tags can be used with the LoginLink and RegisterLink components to track auth traffic from its origin. You can then track the tags on the Analytics dashboard from within the Kinde app.

import {LoginLink} from "@kinde-oss/kinde-auth-nextjs/components";

<LoginLink
  authUrlParams={{
    utm_source: "reddit",
    utm_medium: "social",
    utm_campaign: "redjune23",
    utm_term: "save90",
    utm_content: "desktop"
  }}
>
  Login
</LoginLink>;

Internationalization

Link to this section

You can set the language you wish your users to see when they hit the login flow by including the lang attribute as a part of the authUrlParams when using the LoginLink and RegisterLink components.

import {LoginLink} from "@kinde-oss/kinde-auth-nextjs/components";

<LoginLink
  authUrlParams={{
    lang: "en-AU"
  }}
>
  Login
</LoginLink>;

Audience

Link to this section

An audience is the intended recipient of an access token - for example the API for your application. The audience argument can be passed to the Kinde client to request an audience be added to the provided token.

.env.local

...
KINDE_AUDIENCE=<your-api>

You can request multiple audiences by providing a white space separated list

.env.local

...
KINDE_AUDIENCE=<your-api-1> <your-api-2>

For details on how to connect, see Register an API.

Working with subdomains

Link to this section

In the case you have a custom domain and you would like to start the authentication flow from a URL like auth.mysite.com and you want to redirect to a URL like app.mysite.com , all you have to do is set the KINDE_COOKIE_DOMAIN to match the domain.

.env

...
KINDE_COOKIE_DOMAIN=.mysite.com

If the URL you want to start the authentication flow from and the URL you want to redirect to don’t share the same domain, then this will not work.

Working with preview URLs

Link to this section

Our Kinde NextJS SDK currently requires that these environment variables KINDE_SITE_URL, KINDE_POST_LOGOUT_REDIRECT_URL, and KINDE_POST_LOGIN_REDIRECT_URL are defined, and that the callback URLs and logout redirect URLs are added to your app in Kinde.

To add Vercel’s dynamically generated URLs you can either securely use our API to add them on the fly or you can use wildcard URLs. It should be noted that whilst wildcards are more convenient it is not as secure as explicitly adding the url to the allowlist via API as we outline below.

Add the following to your next.config.js.

/** @type {import('next').NextConfig} */
const nextConfig = {
  env: {
    KINDE_SITE_URL: process.env.KINDE_SITE_URL ?? `https://${process.env.VERCEL_URL}`,
    KINDE_POST_LOGOUT_REDIRECT_URL:
      process.env.KINDE_POST_LOGOUT_REDIRECT_URL ?? `https://${process.env.VERCEL_URL}`,
    KINDE_POST_LOGIN_REDIRECT_URL:
      process.env.KINDE_POST_LOGIN_REDIRECT_URL ?? `https://${process.env.VERCEL_URL}/dashboard`
  }
};

module.exports = nextConfig;

This ensures Vercel uses its generated preview URLs to populate the three Kinde variables.

• Make sure the above values match your application (e.g. “/dashboard” for KINDE_POST_LOGIN_REDIRECT_URL)
• Also make sure variables are not set for the preview environment in your Vercel project. If they are, they will be overridden by the new variables in the next.config.js file.

Add callback URLs and logout redirect URLs to Kinde dynamically

Link to this section

Create a script that will run each time a new preview is deployed by Vercel, which will add the newly generated URL to Kinde.

1. Enable the Kinde Management API for your NextJS app.

   1. In Kinde, go to Settings > Applications and open the Details of your application.
   2. Select APIs in the left menu.
   3. Switch on the Kinde Management API (if it is not on already).
   4. Select Save.

2. In your application source code, create a folder at the top level called scripts.

3. Within that folder, create a file called add-urls-to-kinde.js and add the following code:

   async function getAuthToken() {
     try {
       const response = await fetch(`${process.env.KINDE_ISSUER_URL}/oauth2/token`, {
         method: "POST",
         headers: {
           "Content-Type": "application/x-www-form-urlencoded",
           Accept: "application/json"
         },
         body: new URLSearchParams({
           client_id: process.env.KINDE_CLIENT_ID,
           client_secret: process.env.KINDE_CLIENT_SECRET,
           grant_type: "client_credentials",
           audience: `${process.env.KINDE_ISSUER_URL}/api`
         })
       });
   
       if (!response.ok) {
         throw new Error(`Failed to get auth token: ${response.statusText}`);
       }
   
       const data = await response.json();
       return data.access_token;
     } catch (error) {
       console.error("Error getting auth token:", error);
       throw error;
     }
   }
   
   async function addLogoutUrlToKinde(token) {
     try {
       const response = await fetch(
         `${process.env.KINDE_ISSUER_URL}/api/v1/applications/${process.env.KINDE_CLIENT_ID}/auth_logout_urls`,
         {
           method: "POST",
           headers: {
             Authorization: `Bearer ${token}`,
             Accept: "application/json",
             "Content-Type": "application/json"
           },
           body: JSON.stringify({
             urls: [`https://${process.env.VERCEL_URL}`]
           })
         }
       );
   
       if (!response.ok) {
         throw new Error(`Failed to add logout URL to Kinde: ${response.statusText}`);
       }
   
       const responseData = await response.json();
       console.log(`SUCCESS: Logout URL added to Kinde: ${process.env.VERCEL_URL}`, responseData);
     } catch (error) {
       console.error("Failed to add logout URL to Kinde", error);
       throw error;
     }
   }
   
   async function addCallbackUrlToKinde(token) {
     try {
       const response = await fetch(
         `${process.env.KINDE_ISSUER_URL}/api/v1/applications/${process.env.KINDE_CLIENT_ID}/auth_redirect_urls`,
         {
           method: "POST",
           headers: {
             Authorization: `Bearer ${token}`,
             Accept: "application/json",
             "Content-Type": "application/json"
           },
           body: JSON.stringify({
             urls: [`https://${process.env.VERCEL_URL}/api/auth/kinde_callback`]
           })
         }
       );
   
       if (!response.ok) {
         throw new Error(`Failed to add callback URL to Kinde: ${response.statusText}`);
       }
   
       const responseData = await response.json();
       console.log(
         `SUCCESS: Callback URL added to Kinde: ${process.env.VERCEL_URL}/api/auth/kinde_callback`,
         responseData
       );
     } catch (error) {
       console.error("Failed to add callback URL to Kinde", error);
       throw error;
     }
   }
   
   (async () => {
     if (process.env.VERCEL == 1) {
       try {
         const authToken = await getAuthToken();
         await addCallbackUrlToKinde(authToken);
         await addLogoutUrlToKinde(authToken);
       } catch (error) {
         console.error("Script failed:", error);
       }
     }
   })();

4. In your package.json, add a postbuild script that will run the /scripts/add-urls-to-kinde.js file after Vercel builds your app.

   "scripts": {
       "dev": "next dev",
       "build": "next build",
       "start": "next start",
       "lint": "next lint",
       "postbuild": "node ./scripts/add-urls-to-kinde.js"
   }

5. Commit these changes. The next deploy will add the newly created preview URLs to your Kinde application.

Health check

Link to this section

To check your configuration, the SDK exposes an endpoint with your settings.

Note: The client secret will indicate only if the secret is set or not set correctly.

/api/auth/health

{
  "apiPath": "/api/auth",
  "redirectURL": "http://localhost:3000/api/auth/kinde_callback",
  "postLoginRedirectURL": "http://localhost:3000/dashboard",
  "issuerURL": "https://<your_kinde_subdomain>.kinde.com",
  "clientID": "<your_kinde_client_id>",
  "clientSecret": "Set correctly",
  "postLogoutRedirectURL": "http://localhost:3000",
  "logoutRedirectURL": "http://localhost:3000"
}

Debug mode

Link to this section

In debug mode you will see more logs in your console that may help with debugging.

.env

KINDE_DEBUG_MODE = true;

Migration guide

Link to this section

Changes when moving from the previous version.

handleAuth - is now imported from “@kinde-oss/kinde-auth-nextjs/server”

import {handleAuth} from "@kinde-oss/kinde-auth-nextjs/server";
export const GET = handleAuth();

getKindeServerSession - functions returned from getKindeServerSession now return promises

const {getUser} = getKindeServerSession();
const user = await getUser();