Sync your First User using the SDK

Syncing a user is one of the most integral parts of using Permit, as it serves as the handoff point between your application's user management system and our policy engine.

tip

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

In this guide, 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.

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 guide 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.

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.

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.

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:

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

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.

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:

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

Default Tenant

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.

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?