Connect Your Authentication

Connect your authentication provider to Permit.io so every signed-in user exists in Permit and gets the right roles. This page is for developers who add Permit to an application that already has sign-in. Find your provider below, or follow the steps for any other provider or a custom authentication system.

For the concepts behind this page (the handoff point, the user key, and where to manage roles), read How authentication connects to Permit.io.

Prerequisites

• A Permit.io account with a policy: roles, resources, and permissions. The Quickstart sets one up.
• Your environment API key. See Get your API key.
• An application where users already sign in with your authentication provider.

Find the guide for your provider

Provider	Guide	What the guide covers
Auth0	Auth0 and Permit integration	Sync users and Auth0 roles at login in a Next.js app
Auth0	Auth0 demo application	Run the Next.js to-do demo that combines Auth0 and Permit
Auth0	Sync Auth0 users and roles	Export existing Auth0 users and import them with a Python script
AWS Cognito	Cognito and Permit integration	Verify Cognito tokens, sync users, and check permissions in a Node.js backend
AWS Cognito	Cognito demo application	Run the vanilla JavaScript and Express demo
Stytch	Stytch and Permit integration	Add Stytch sign-in to Next.js, then create a tenant, sync the user, and assign a role
Hanko	Hanko and Permit	Passkey sign-in with role-based and attribute-based checks in a Next.js notes app
Logto	Logto and Permit	Sync users with a Logto webhook and show UI based on permissions
SuperTokens	SuperTokens example	Run an example Next.js app that syncs SuperTokens users at sign-up
FusionAuth	FusionAuth example	Explore an example Express app that syncs FusionAuth users
Okta	SCIM integration with Okta	Provision users and groups from Okta through SCIM
Microsoft Entra ID	SCIM integration with Entra ID	Provision users and groups from Entra ID through SCIM
Keycloak	Keycloak RBAC with Permit.io (blog)	Map Keycloak users to Permit roles

Connect any other authentication provider

If your provider isn't listed, or you run your own authentication, build a handoff point: middleware that runs right after authentication succeeds and before your application serves the user.

1. Verify the user's token

After sign-in, your authentication provider creates a session and issues a token, usually a JSON Web Token (JWT). In your backend, validate the token with the provider's SDK or its public keys. Don't trust a user ID that the browser sends without a verified token.

Fun fact

The JWT format was standardized by the IETF in May 2015 as RFC 7519, authored by Michael Jones, John Bradley, and Nat Sakimura.

2. Pick the user key

Read a stable, unique identifier from the verified token, such as the sub claim. Permit uses this value as the user key. Pass the same key to every sync call, role assignment, and permission check for that user.

3. Sync the user to Permit

At the handoff point, call syncUser() with the user key, and optionally the email, first name, last name, and attributes from the token. syncUser() creates the user if the key is new and updates the user if the key exists.

• SDK usage and parameters: Sync users and the Node.js syncUser reference.
• API: Create user.

4. Assign a role

A synced user with no role assignment gets a deny from every role-based check. Assign a role in a tenant (use the default tenant if you don't use multi-tenancy):

• SDK: Node.js assignRole reference.
• API: Assign role to user.

If your provider already stores roles, map each provider role to a Permit role with the same key. Role keys are case-sensitive.

5. Verify the user in Permit

Sign in to your application with a test user. Then open Directory in the Permit dashboard. The user appears with the key from step 2 and the role from step 4. Call permit.check() for an action that role allows. The check returns true.

Import existing users in bulk

The handoff point syncs users when they sign in. Users who don't sign in after you add the integration stay missing from Permit. Import them in one operation:

1. Export the users from your authentication provider, with the same identifier you use as the user key.
2. Send them to the bulk create users endpoint, POST https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/users, or call the bulk methods in an SDK. See Bulk user operations for the request format and limits.
3. Assign roles to the imported users. See Bulk role assignment.
4. Open Directory in the Permit dashboard and confirm the imported users appear with their roles.

Next steps

• How authentication connects to Permit.io: compare sync methods and role ownership models.
• Check permissions: enforce the policy with permit.check().
• SCIM overview: provision users from an identity provider without handoff code.