Skip to main content
Version: 2.0.0

User Management Element

Effortlessly manage users and their permissions as a single secure, embeddable UI component.

The User Management Element is an embeddable UI component that lets you take control of your whole team, and give other team members specific permissions levels that reflect how they can manage other users on your team.

User Management Element

Understanding the Element

There are two primary ways you can configure permissions using this element:

Role-Based Access Control (RBAC) Roles:

What is it? - This method lets you manage system-level access based on roles. How does it work? - It's straightforward—assign predefined meta permission roles to determine what level of access a user has. Think of it as giving someone with a specific role, a new definition of what that role can do for this specific element.

Relationship-Based Access Control (ReBAC) Resource Roles:

What is it? - This method lets you manage access at a more granular level, allowing you to specify permissions for individual resource instances based on their type. How does it work? - Initially, the user selects the specific resource they want to manage. Based on the resource roles previously defined in Permit, users can drag these roles to align them with the desired meta-permission levels. This process determines which roles can interact with which resources.

Interacting with the UI

Once you've set permissions, the UI visualization on the right side of the element provides valuable feedback:

  • Role View: This lets users see how the element appears based on different permission levels and tenants. It's a useful way to confirm that you've set everything up correctly.

  • ReBAC Resource Switching: For those using ReBAC, there's an additional feature. Users can toggle between specific instances of a resource. This means they can view and manage permissions for individual resource instances.

Embedding the Element

Initializing Permit


In order to use Permit Elements, you need to be a user of Permit. When starting to use Permit, you will need to initialize an instance of Permit in your backend logic. This only needs to be done once, both to use Permit and Elements. Please remember to copy your SDK Secret Key and pass it into the initialized Permit object.

1 2 3 4 const { Permit } = require("permitio"); const permit = new Permit( {token: permit_key_SECRET} );

Server-side Login Route

You need to create a route in your backend server to allow your client to loginAs themselves and get access the Permit Element.

The backend loginAs route is matched based on the Authentication methods you have implemented inside your App. Most applications authenticate with the Bearer Token or Cookies, but we also allows you to use any other HTTP Security Header. The important part here is, that you use the appropriate code example below based on your Authentication method.

The loginAs function takes two parameters. You need to pass in the unique userId you get from your JWT (JSON Web Token), and a tenant_key or tenantId.

permit.elements.loginAs({ userId, tenant });

The user must belong to the tenant that he will be logged into. If he is not, you will see a login error saying USER_NOT_FOUND.

If the user gets logged out, he also exits the current tenant specificed in the loginAs method. If you want to change tenants for a user, you need to log them out, and log them back in to a different tenant.

Passing in the tenant is compulsory when logging in a user server-side.

2.1Using CookiesServer-side
2.2Using Bearer TokenServer-side
2.3Using Other HeadersServer-side
2.4Using FrontendOnlyServer-side

Install Permit-js

Once you have your application ready, you need to install Permits's JS SDK. This gives you access to our prebuilt embeddable Element components.


Add the Permit JavaScript SDK to you app:

# Navigate to your application's root directory cd yourapp npm install –-save @permitio/permit-js

Client-side login method

This function should be called as early as possible in your App. This is best done inside a App/index file; right after the users had just had their identity confirmed by the Authorization provider you are using, but just before the Embedded component is loaded.

With any of these login frontend methods, it's optional to pass in your tenant key, in comparison to the server-side call where it is required. The server-side tenant will always take precedence. We do however encourage passing in the same tenant in your frontend and backend login calls for best practices and for adding clarity to your code.


This is the permit element object that is calling the backend route we have configured previously and logging in the user.

1 2 3 4 5 6 7 8 permit.elements.login({ loginUrl: ', tenant: 'your_tenant_key', token:'<TOKEN>', loginMethod: LoginMethod.bearer }).then((res: any) => {//optional handle success }).catch((err: any) => {//handle error });

There are four things that need to be configured here:

  1. loginUrl - The url that corresponds to your backend login route you created in the last step.
  2. loginMethod - The login method you are using in your backend.
  3. tenant (Optional) - Required for frontendOnly login method. the name of the tenant that the user is part of, you can set it at your backend as well, if you are using frontendOnly this is required.
  4. token (Optional) - Required for bearer token login method, you need to pass the token here.
  5. headers (Optional) - Required for custom headers login method, you need to pass the headers here.
  6. userJwt (Optional) - Required for frontendOnly login method, you need to pass the user jwt here.
  7. envId (Optional) - Required for frontendOnly login method, you need to pass the env id here.

There are 3 supported login options choose the one that you are using in your backend.

4.1Cookie Login MethodClient-side
4.2Bearer Token Login MethodClient-side
4.3Other Header Login MethodClient-side
After you run login successfully you will **get a cookie** called `permit_session` which will allow you to load your Permit Element securely and successfully.

Client-side logout method

This function should be called along with the logging-out logic that you have within your App, to make sure the user does not continue to have access to the Permit Element.


This logout method should be called as part of the logic of logging your user out with your authentication solution.

1 permit.elements.logout();

Login Errors

There are a few possible errors you might find yourself come across while working with the embedding of Permit Elements.

USER_NOT_FOUNDThis error can appear if you are trying to log in as a particular user, but that user does not exist within Permit. You can also experience this login error when you are trying to login a user into a tenant that he does not belong to.
TENANT_NOT_FOUNDThis error can appear when you are passing in a tenant, either in the frontend permit.elements.login function, or in your backend URL endpoint, where the tenant has not been created in Permit.
INVALID_PERMISSION_LEVELThis error will emerge when you are trying to access part of the Element which you have not been given access too. This usually means the role that the person obtained has remained in the Hidden Roles permission level.
FORBIDDEN_ACCESSThis error will emerge when you are trying to login to an Element you have not been given permission to see.

Customizing your Element

Each element offers customization and configuration.

Match your brand

With every new element, you will be able to adjust several setting to make the look and feel of the element really your own.

  • Change the background and primary colour of any element to match your brand.
  • Give the element a title that makes sense to your end user, or hide it fully.
  • Decide if you want to display your users Email, Full Name or both on the element.

Audit Logs Element

Configure your webhook

Webhooks are automated messages sent from apps when something happens. They carry data in 'payloads', which are sent to a unique URL, essentially a place where your API can accept data.

With some Permit Elements, you will get the option to configure a webhook to stay informed of the actions that are performed by the end users.



The User Management Element's webhook provides an array of functionalities. For example, you can leverage it to receive notifications each time a new user is created in your system, or to initiate the sending of a welcome message to recently invited users.

Setting Up the URL Endpoint

Before setting up a URL endpoint, it's important to note that the URL endpoint is the URL to which the webhook delivers data each time an event occurs. This endpoint should be set up on your server or a third-party service, depending on your preference.

Choose Your Platform:

Decide whether you want to set up your endpoint on your own server or use a third-party service. If you're comfortable managing a server and can handle potential scaling, security, and uptime issues, you may prefer to host it yourself. Otherwise, consider using a third-party service, many of which handle these issues for you.

Create the Endpoint:

Create a new endpoint on your server or within your chosen third-party service. This is often a case of creating a new URL route. For example, /new-element-sure or /send-elements-email.

Implement Webhook Handling:

Your endpoint needs to be able to receive POST requests, as webhooks will typically send data via this method. This means your endpoint needs to be set up to read the payload from incoming POST requests and then process it as required. This usually involves parsing JSON, although the exact format may vary.

The expected payload of the webhook will include the following fields:

  • Email
  • Tenant id
  • Role
  • Permission level
  • Type

Here is an example for the payload:

"email": "",
"role": "admin",
"tenant_key": "default",
"permission_level": "LEVEL_3"
"type: "create_user"

Secure Your Endpoint:

Webhooks contain data, and you should ensure it's secure from potential malicious use. Within the Permit configuration screen, we provide a input box so you can enter your secret, and use it to validate incoming data. This will ensure that the data is coming from a trusted source. Also, ensure your endpoint uses HTTPS, encrypting data in transit.


Respond to the Webhook:

After receiving a POST request, it's good practice to send a 200 HTTP status code to acknowledge receipt of the data. If your endpoint fails to do this, the webhook may consider the delivery a failure and retry, causing unnecessary traffic.

Embedding the iFrame

After you finish configuring and customising your element, you are ready to it into your App. A code snippet for the element will be generated for you. This will be an <iframe> that you can insert anywhere into your website. It will look like the code snippet below.

title="Permit Element Name"
style="border: none;"

If you end up creating an element to manage meta-permissions for resource instances, when you go ahead to copy the embed code, not only will you have the option to pick the tenant you want this snippet to work for, you will also be able to select the resource instance for the embed.

Resource Instance Selection

Was this page helpful?
Questions? Contact Us.Watch our developer tutorials.Need help? Join our Slack.
Sign up for developer updates:
You can unsubscribe at any time. Read our privacy policy.