Skip to main content
Version: 2.0.0

Sync your First User

Syncing users is one of the most integral parts of using Permit, as it serves as the handoff point between your application's user management system (usually Authentication or IdP) and the Permit authorizaiton control-plane.

NOTE

Users are the name we use for both human and machine identities.

TL;DR​

Sync users on-the-fly by passing their unique ID to the createUser API or users.create/sync SDK call. This should be done as part of your Authentication callback.

  1. Newly added users would appear in the Directory under All Tenants.
  2. Assign roles to users to also link them to specific tenants.
  3. You can assign multiple users to multiple roles at multiple tenants.
  4. You can use the bulk API to load multiple users at once.

When to sync your users?​

The ideal time to sync users into Permit is during sign-in or sign-up, right after authentication verifies their identity. At this stage, map their organizational role (e.g., Head of Marketing, Customer, or Patient) and relevant JWT claims to application-level roles, attributes, and relationships. This ensures their permissions align immediately with their role and streamlines access management.

Our API Reference​

In this walkthrough, we’ll show you how to sync your first user into Permit using the API, ensuring they’re already assigned a role, or ready to be assigned roles and permissions within your access control model.

We will be making use of two separate endpoint in our API:

  1. Creating a user
  2. Assigning a role to a user
note

If you would like to do some further reading on understanding the Permit Hierarchy, you can find it here.

1

Sync Users from your identity provider​

To create a user in Permit, you need to make a POST request to the users endpoint using your project ID (proj_id), environment ID (env_id), and the user's unique details. This ensures the user is properly synced into the specified environment and ready for role assignments.

No files found in the specified folder path.
Sync Users via SCIM

Permit supports user synchronization through SCIM (System for Cross-domain Identity Management). This allows seamless integration with identity providers like Entra ID, Okta, and others. SCIM simplifies user management by automatically provisioning, updating, and de-provisioning users in Permit.

2

Verify the user was created in the Permit Directory​

In this case, we will use cURL to run this request and as a result, we achieve a new user that's created in the UI, under the Directory.

Copy secret key from user menu
tip

As part of the POST request, or in this example the userData object, you can directly assign roles to the user upon creation. Simply include the role_assignments field in the request body, such as:

role_assignments: [{ role: "manager", tenant: "default" }];

This allows you to streamline the user creation process by immediately associating them with the appropriate role and into the right tenant.

Below is the request in Postman for adding a user with a role assignment:

Copy secret key from user menu

And therefore the result of this request in the Permit directory:

Copy secret key from user menu
3

Assign a role to the User (optional)​

Once the user is created, you can choose to make another API request to assign a role to the user. This is done by calling the following endpoint.

No files found in the specified folder path.
4

Create a new tenant​

In Permit, a tenant represents an isolated space within your application where roles, resources, and permissions are separated. This enables multitenancy, allowing the same user to exist in multiple tenants with different roles (e.g., Admin in one tenant and Manager in another), ensuring their permissions are context-specific.

In this example, we will create a new tenant called Marketing.

No files found in the specified folder path.

The result of this SDK call being successful, is the creation of a new tenant, which we can see below:

Copy secret key from user menu
5

Add a user to a new tenant and assign them a different role​

It is now time to guide you through adding a user to a new tenant and assigning them a specific role, ensuring their permissions are customized for that tenant.

No files found in the specified folder path.

The result of this SDK call being successful, is the creation of a the same user that already exists in a different, in our new Marketing tenant, but with a Manager role (rather than an `Employee' role) - which we can see below:

Marketing Tenant​

Copy secret key from user menu

Default Tenant​

Copy secret key from user menu

Bulk user syncing​

Our API also supports syncing and updating users en-masse.

What did you learn?​

In this guide, you’ve learned how to:

  • Sync a user into Permit using the API.
  • Assign roles to a user either during creation or later through a dedicated API call.
  • Understand Permit’s hierarchy (workspaces, projects, environments) and how it relates to API calls.
tip

Permit is fully API-driven, providing a seamless way to programmatically manage everything you can do via our no-code UI.

FUN FACT!

Ever heard of the Cat Facts API? Developers created it as a joke, but it became a hit for testing API integrations while sending random cat facts.

What's next? 🎉

  • Understand the check() function
  • Run a local Policy Decision Point
  • Perform an authorization check

Great stuff. Ready to learn more?

Contents