NodeJS SDK
Kinde’s NodeJS SDK helps developers integrate a new or an existing NodeJS application to the Kinde platform.
You can view the NodeJS docs and NodeJS starter kit in GitHub.
Requirements
Link to this section- Node version 18.x.x or newer.
- If you haven’t got a Kinde account, register for free here (no credit card required). Registering gives you a Kinde domain, which you need to get started, e.g.
yourapp.kinde.com
.
Install
Link to this sectionConfigure Kinde
Link to this sectionSet callback URLs
Link to this section-
In Kinde, go to Settings > Applications > [Your app] > View details.
-
Add your callback URLs in the relevant fields. For example:
-
Allowed callback URLs (also known as redirect URIs):
https://<your_app_domain>/callback
e.g:http://localhost:3000/callback
-
Allowed logout redirect URLs:
https://<your_app_domain>
e.g:http://localhost:3000
-
-
Select Save.
Add environments
Link to this sectionKinde comes with a production environment, but you can set up other environments if you want to. Each environment has a unique subdomain so be sure to use the correct one in the Configure your app section which follows.
Configure your app
Link to this sectionEnvironment variables
Put these variables in your .env
file. You can find these variables on your Settings > Applications > [Your app] > View details page.
KINDE_DOMAIN
- your Kinde domainKINDE_CLIENT_ID
- your Kinde client IDKINDE_CLIENT_SECRET
- your Kinde client secretKINDE_REDIRECT_URL
- your callback url to redirect to after authentication. Make sure this URL is under your Allowed callback URLs.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.
Below is an example of a .env
file
Integrate with your app
Link to this sectionCreate a new KindeClient
instance before you initialize your app.
Sign in and sign up
Link to this sectionTo incorporate the login and register features, you’ll have to create routes for /login
and /register
. Additionally, you should implement the login
/register
methods in the middleware.
Add links in your HTML as follows:
Manage redirects
Link to this sectionYou will also need to route /callback
. When the user is redirected back to your site from Kinde, it will trigger a call to the callback URL defined in the variable KINDE_REDIRECT_URL
.
Logout
Link to this sectionThe Kinde SDK comes with a logout method.
Add links in your HTML as follows:
Check if user authenticated
Link to this sectionWe’ve provided a helper to get a boolean value to check if a user is signed in. This verifies that the access token is still valid.
View user profile
Link to this sectionYou need to have already authenticated before you call the API, otherwise an error will occur.
To access the user information, use the getUserDetails
helper function:
View users in Kinde
Link to this sectionIf you navigate to the “Users” page within Kinde you will see your newly registered user there.
Audience
Link to this sectionAn 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.
The audience of a token is the intended recipient of the token.
For details on how to connect, see Register an API
Overriding scope
Link to this sectionBy default the KindeSDK
requests the following scopes:
- profile
- offline
- openid
You can override this by passing scopes into the KindeSDK
.
Organizations
Link to this sectionCreate an organization
Link to this sectionTo have a new organization created within your application, you will need to set up the following route
You can also pass org_name
as part of the query string as per the following HTML:
Sign up and sign in to organizations
Link to this sectionThe Kinde client provides methods for you easily sign up and sign in users into organizations. You can add links in your HTML as follows:
Following authentication, Kinde provides a json web token (jwt) to your application. Along with the standard information we also include the org_code
and the permissions for that organization (this is important as a user can belong to multiple organizations and have different permissions for each).
Example of a returned token:
The id_token
will also contain an array of organizations that a user belongs to - this is useful if you wanted to build out an organization switcher for example.
There are two helper functions you can use to extract information:
For more information about how organizations work in Kinde, see Kinde organizations for developers.
User permissions
Link to this sectionOnce a user has been verified, your product/application will return the JWT token with an array of permissions for that user. You will need to configure your product/application to read permissions and unlock the respective functions.
Set permissions in your Kinde account. Here’s an example set of permissions.
We provide helper functions to more easily access the permissions claim:
A practical example in code might look something like:
Getting claims
Link to this sectionWe have provided a helper to grab any claim from your id or access tokens. The helper defaults to access tokens:
Feature flags
Link to this sectionWe have provided a helper to grab any feature flag from access_token
:
We also require wrapper functions by type which should leverage getFlag
above.
Get boolean flags
Link to this sectionGet string flags
Link to this sectionGet integer flags
Link to this sectionToken storage
Link to this sectionAfter the user has successfully logged in, you will have a JSON Web Token (JWT) and a refresh token securely stored. You can retrieve an access token by utilizing the getToken
method.
Kinde Management API
Link to this sectionYou 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
SDK API reference
Link to this sectiondomain
Link to this sectionEither your Kinde instance url or your custom domain. e.g. https://yourapp.kinde.com
Type: string
Required: Yes
clientId
Link to this sectionThe unique ID of your application in Kinde.
Type: string
Required: Yes
clientSecret
Link to this sectionA unique secret code/key of your application in Kinde.
Type: string
Required: Yes
redirectUri
Link to this sectionThe URL that the user will be returned to after authentication.
Type: string
Required: Yes
logoutRedirectUri
Link to this sectionWhere your user will be redirected to when they sign out.
Type: string
Required: Yes
grantType
Link to this sectionDefine the grant type when using the SDK.
Type: string
Required: Yes
audience
Link to this sectionThe audience claim for the JWT.
Type: string
Required: No
scope
Link to this sectionThe scopes to be requested from Kinde: openid
profile
email
offline
.
Type: string
Required: No
KindeSDK methods
Link to this sectionlogin
Link to this sectionConstructs a redirect URL and sends the user to Kinde to sign in.
Usage:
register
Link to this sectionConstructs a redirect URL and sends the user to Kinde to sign up.
Usage:
logout
Link to this sectionLogs the user out of Kinde.
Usage:
callback
Link to this sectionCallback middleware function for Kinde OAuth 2.0 flow.
Usage:
isAuthenticated
Link to this sectionCheck if the user is authenticated.
Arguments:
Usage:
Output: true
or false
createOrg
Link to this sectionConstructs redirect url and sends user to Kinde to sign up and create a new org for your business.
Arguments:
Usage:
getClaim
Link to this sectionGets a claim from an access or ID token.
Arguments:
Usage:
Output: 'David'
getPermission
Link to this sectionReturns the state of a given permission.
Arguments: key
: string
Usage:
Output sample:
getPermissions
Link to this sectionReturns all permissions for the current user for the organization they are logged into.
Arguments:
Usage:
Sample output:
getOrganization
Link to this sectionGet details for the organization your user is logged into.
Arguments:
Usage:
Sample output:
getUserDetails
Link to this sectionReturns the profile for the current user.
Arguments:
Usage:
Sample output:
getUserOrganizations
Link to this sectionGets an array of all organizations the user has access to.
Arguments:
Usage:
Sample output:
getFlag
Link to this sectionGet a flag from the feature_flags claim of the access_token
.
Arguments:
Usage:
Sample output:
getBooleanFlag
Link to this sectionGet a boolean flag from the feature_flags
claim of the access token.
Arguments:
Usage:
Sample output: true
getStringFlag
Link to this sectionGet a string flag from the feature_flags
claim of the access token.
Arguments:
Usage:
Sample output: pink
getIntegerFlag
Link to this sectionGet an integer flag from the feature_flags
claim of the access token.
Arguments:
Usage:
Sample output: 2
If you need help connecting to Kinde, please contact us at support@kinde.com.