Policy Basics

Learn the building blocks of a Permit.io policy (resources, actions, roles, users, and tenants) and where you create each one in the Permit dashboard. This page is for developers who are new to Permit and want to understand the model before they build their first policy.

You define the policy schema (resources, actions, and roles) on the Policy screen, which includes the Policy Editor. You add the data the policy evaluates (users, tenants, and role assignments) on the Directory screen. Permit generates policy code from what you configure, and your policy decision points (PDPs) evaluate that code when your application calls permit.check().

The first sections define each building block. Do each task in the Permit dashboard then lists the steps for each dashboard task, with a video of the same flow.

What is a policy?

A policy is the set of rules that decides whether a user can perform an action on a resource.

• The most basic policy consists of roles, actions, and resources: a role is allowed to perform an action on a resource.
• A policy belongs to an environment. Each environment in a project has its own policy.

Supported authorization models

A Permit policy can grant permissions in three ways, and you can combine them in one policy:

Model	Grants permissions based on	Learn more
Role-based access control (RBAC)	The roles assigned to the user	RBAC overview
Relationship-based access control (ReBAC)	The user's relationship to a specific resource instance	ReBAC overview
Attribute-based access control (ABAC)	Attributes of the user, resource, or tenant	ABAC overview

To compare the models and see how they combine, read Mix and Match Policies.

Define resources and actions

Resources and actions are the base of every policy. You define them on the Resources tab of the Policy screen, or through the Permit API.

Resources

A resource is an object type you want to control access to, such as a document, a board, or an API endpoint. Resources belong to an environment.

For example, in a social media application, the resources could be user profiles, posts, comments, and private messages.

Actions

An action is an operation a user can perform on a resource. Each resource has its own list of actions, so an action such as sign can exist on one resource only.

For example, in a music streaming application, the actions on a song resource could be play, skip, add_to_playlist, download, and share.

How roles, resources, and actions form permissions

In the Policy Editor, each role has a checkbox for every action of every resource. When the checkbox is selected, users with that role can perform that action on that resource.

The screenshot shows the admin role of a policy with three resources: Board, Document, and Task. The admin role holds every action on Board, create and update on Document, and read on Task. The sign action exists on Document only.

Default permissions

When you create a resource in the Policy Editor, Permit adds a default set of actions to the resource and grants default permissions to default roles. The Default Permissions panel of the environment holds those defaults. The panel in the screenshot below holds these values:

Role	Actions
admin	create, read, update, delete
editor	create, read, update
viewer	read

The panel is editable, so the defaults in an environment can differ from this table. To read or change them, click Settings in the Policy Editor. You can edit the default actions and roles, or turn off Assign the Default Permissions to every new resource.

Roles and permissions

A policy grants permissions to roles, and you assign roles to users per tenant.

Roles

A role is a named collection of permissions that you assign to users. Instead of granting permissions to each user, you grant them to a role and assign the role to users. For example, a company application could have manager, engineer, and hr roles, each with a different set of permissions.

Roles are defined per environment: you create them on the Roles tab of the Policy screen, or through the Permit API. Each environment has its own set of roles.

The roles described on this page are top-level roles: a user holds a top-level role across a whole tenant. The Directory screen shows them in the Top Level Access column. For roles on a specific resource instance, see Resource roles.

You assign roles to users on the Directory screen, per tenant.

Manage users and tenants

On the Directory screen, you can:

• Create, update, and delete users.
• Assign roles to users.
• Add users to tenants.

You can also manage users and tenants with the Permit API and SDKs. See Sync users.

Users and members

Users are the identities you check permissions for, such as the people who sign in to your application. Members are your team in the Permit dashboard, managed in workspace settings.

Users

A user is an identity that your application checks permissions for. A user is usually a person, and can also be a service or an automated process.

Each user has a unique key. You use the key to identify the user in permit.check(). A user can also have an email, a first name, a last name, and attributes.

A user belongs to one or more tenants, and has role assignments in each tenant. The same user can hold different roles in different tenants. The Users tab of the Directory screen lists each user with its key and the roles it holds in the selected tenant.

Tenants

A tenant is an isolated group of users and resources inside an environment. In a multi-tenant application, each tenant usually represents one of your customers (the company that you sell to).

Role assignments are scoped to a tenant. A user with the admin role in tenant acme doesn't have that role in tenant globex unless you assign it there too. To use the same user in several tenants, add the same user key to each tenant.

To learn more, see Multi-tenant authorization.

Do each task in the Permit dashboard

Each task below lists the steps in the Permit dashboard, followed by a video of the same flow. The tasks are independent, so you can run the one you need. For an end-to-end policy with a worked example, follow Building an RBAC policy or Building your first ABAC policy.

Create a role

1. Open the Policy screen and select the Roles tab.
2. Create a role. The New Role panel opens.
3. Enter a name, such as Admin. Permit fills Key from the name. Use the key in your code and in API calls.
4. Click Save. The role appears in the list on the Roles tab.

Create a resource

1. Open the Policy screen and select the Resources tab.
2. Click Add Resource. The New Resource panel opens.
3. Enter a name, such as document. Permit fills Key from the name.
4. In Actions, type each action and press Enter after each one. An action that you type without pressing Enter is not added.
5. Click Save. The Policy Editor then shows a checkbox for each action of the resource, under every role.

Add a user and assign a role

1. Open the Directory screen and select the Users tab.
2. Click Add user. The Create a new user panel opens.
3. Enter a Key that identifies the user in permit.check(). The email, first name, and last name are optional.
4. Select the Tenant the user belongs to, such as Default Tenant.
5. Under Top Level Access, add each role the user holds in that tenant.
6. Click Save. The user appears on the Users tab with its key, and its roles in the TOP LEVEL ACCESS column.

For the same task with screenshots and a worked example, see Create a user and assign the Admin role.

Assign multiple roles to a user

A user can hold several top-level roles in the same tenant.

1. On the Users tab of the Directory screen, open the three-dot menu of the user and select Edit.
2. Under Top Level Access, add each role the user needs.
3. Click Save. The TOP LEVEL ACCESS column of the user lists every role you assigned.

Give permissions to a role

1. Open the Policy screen and select the Policy Editor tab.
2. Select the checkbox of each action the role can perform on a resource.
3. Click Save Changes in the bar that counts your unsaved changes. To drop the changes instead, click Reset.

Create a tenant

1. Open the Directory screen and click Settings.
2. Select Manage Tenants under General, then add a tenant. The Tenant dialog opens.
3. Enter a Name, and optionally a description. To set tenant attributes, click Edit Tenant Attributes.
4. Click New Tenant. The tenant appears in the list with the key Permit generated from the name.

Switch between tenants

A user can have different roles in each tenant, so switching tenants on the Directory screen shows different role assignments for the same user.

1. Open the Directory screen and select the Users tab.
2. Open the tenant selector at the top of the screen. A new environment has one tenant, Default Tenant, whose key is default.
3. Select a tenant. The Users tab lists the users who hold a role in that tenant, and the TOP LEVEL ACCESS column shows the roles they hold there.

Switch the Policy Editor view

The Policy Editor has two views: a block view with one card per role, and a grid view with one column per role.

1. Open the Policy screen and select the Policy Editor tab.
2. Click the grid view button or the block view button in the top-right corner, next to Create.

In the grid view, click a resource name to expand its actions. The checkbox in the resource row covers every action of the resource, and shows a dash when the role has only some of them.

Confirm the policy works

Run a permission check for the role, resource, and user you created. The following check asks whether the user john@permit.io can perform read on document:

const permitted = await permit.check("john@permit.io", "read", "document");

console.log(permitted);

The script prints true when john@permit.io holds a role that permits read on document in the tenant of the check:

true

For the SDK client setup and the rest of the check options, see Check permissions with permit.check(). When a check returns false and you expected true, see Fix a no_permission denial.

Policy code generated by Permit

Permit generates policy code from what you configure in the Policy Editor. The PDP runs Open Policy Agent (OPA) with the Rego language, or Cedar. See an example of generated Rego code.

Open Policy Administration Layer (OPAL) delivers policy updates from the Permit control plane to each PDP you run. To learn how this works, see Control & Data planes.

Fun fact

AWS open-sourced the Cedar policy language and authorization engine on May 10, 2023, under the Apache License 2.0. Read the AWS announcement.

Manage policy as code with GitOps

With the GitOps feature, Permit saves the policy code it generates to a Git repository that you own, before the code is deployed to your PDPs. You can then use your existing Git workflow on policy changes: version history, code reviews, tests, and approvals. You can also add your own Rego code next to the generated code.

To set up GitOps, see Git and Permit. For an overview, see GitOps overview.

Next steps

• Building an RBAC policy: create roles, a resource, permissions, and a user.
• Building your first ABAC policy: create user sets and resource sets from attributes.
• Building ReBAC policies: define relations and role derivations.
• Check permissions with permit.check(): enforce the policy in your code.