Build an RBAC policy with the API

Build a role-based access control (RBAC) policy for a shared to-do app with curl calls to the Permit REST API. This page is for developers who set up policies from scripts instead of the Permit dashboard. At the end, an admin user can perform every action on tasks, and an operator user can read and toggle tasks.

Example policy for a shared to-do app

The to-do app lets users create, read, update, toggle, and delete tasks. The policy has three parts:

Part	Definition
Roles	admin and operator
Resource	task, with the actions create, read, update, toggle, and delete
Permissions	admin can perform every action. operator can read and toggle tasks.

Prerequisites

• An environment API key. See Get your API key.
• The ID or key of your project and environment. See Get the project and environment IDs.

In every command on this page, replace these placeholders:

Placeholder	Replace with
API_SECRET_KEY	Your environment API key
{project_id}	Your project ID or project key
{env_id}	Your environment ID or environment key

1. Create the roles, resource, and role permissions

The following commands create the admin and operator roles, create the task resource with its five actions, and assign permissions to each role. Permissions use the format <resource>:<action>.

# create an admin role
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/roles' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"key":"admin","name":"admin","description":""}'

# create an operator role
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/roles' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"key":"operator","name":"operator","description":""}'


# create a task resource with create, read, update, toggle and delete actions
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/resources' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"key":"task","name":"task","actions":{"create":{"name":"create"},"read":{"name":"read"},"update":{"name":"update"},"toggle":{"name":"toggle"},"delete":{"name":"delete"}},"attributes":{}}'


# create a role permission for admin
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/roles/admin/permissions' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"permissions":["task:create","task:read","task:update","task:toggle","task:delete"]}'

# assign permissions to the operator role
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/roles/operator/permissions' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"permissions":["task:read","task:toggle"]}'

Request	Endpoint
Create a role	POST /v2/schema/{project_id}/{env_id}/roles
Create a resource	POST /v2/schema/{project_id}/{env_id}/resources
Assign permissions to a role	POST /v2/schema/{project_id}/{env_id}/roles/{role_key}/permissions

2. Create the users

The following commands create two users: one for the admin role and one for the operator role. Replace the example keys and emails with your own users.

# create the first user (assigned to the admin role below)
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/users' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"key":"unique_id_for_admin_username","email":"admin@domain.com","first_name":"","last_name":""}'

# create another user
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/users' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"key":"unique_id_for_username","email":"user@domain.com","first_name":"","last_name":""}'

Users are created with POST /v2/facts/{project_id}/{env_id}/users. The key field is required and must match the user identifier your application passes to permission checks.

3. Assign roles to the users

The following commands assign the admin role to the first user and the operator role to the second user, both in the default tenant.

# assign the admin user to the admin role
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"role":"admin","tenant":"default","user":"unique_id_for_admin_username"}'

# assign the operator role to the second user
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"role":"operator","tenant":"default","user":"unique_id_for_username"}'

Role assignments are created with POST /v2/facts/{project_id}/{env_id}/role_assignments. The role and user fields are required.

4. Verify the policy

Send a GET request to https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments?user=unique_id_for_username with the same authorization header. The response lists one assignment with role set to operator and tenant set to default.

To confirm that the permissions behave as expected, run a permission check for the operator user. A check for toggle on task returns true, and a check for delete on task returns false. See Check permissions.

Next steps

• Check permissions from your application with the Permit SDK.
• Build ABAC policies with the API when roles alone don't express your rules.
• Browse the full API reference for every endpoint used on this page.