Perform Bulk Operations
Navigate through the various bulk operations supported in Permit and their usage.
Bulk operations on data are key for any system built to scale, helping developers perform large operations on data in a single request. In an authorization system, this is especially true for operations required as part of the user sync and graph policy updates.
While all the operations in this document are performed as plain HTTP requests, our SDKs support many of these operations in a more convenient way.
Information about SDK support of various operations can be found on the SDK feature parity page
In case there is a feature missing, please let us know in the community.
Bulk Operations Glossary
Bulk User Operations
When working with Permit, users are the main focus of our system, as we wish to control what they can access. Because Permit focuses on authorization and not identity management, user data is usually managed in external systems and synced into Permit. The most efficient way to sync your initial user data, or to update a large number of users, is by using bulk user operations.
The following bulk user operations are supported:
# Create new users
curl -X POST https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/users \
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"operations": [{
"key": "jane_doe",
"email": "jane@coolcompany.com",
"first_name": "Jane",
"last_name": "Doe",
"attributes": {}
}, ...]
}'
# Update existing users
curl -X PUT https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/users
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"operations": [{
"key": "jane_doe",
"email": "test@permit.io",
"first_name": "Jane",
"last_name": "Doe",
"attributes": {}
}, ...]
}'
# Delete existing users
curl -X DELETE https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/users
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"idents": ["jane_doe", ...]
}'
Bulk Tenant Operations
Tenants are the silos that hold users, helping you to model account -> user in the same way your application does.
If you'd like to perform bulk operations on users, you might also want to perform bulk operations on tenants.
The following bulk tenant operations are supported:
# Create new tenants
curl -X POST https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/tenants \
-
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"operations": [{
"key": "cool_company",
"name": "Cool Company",
"attributes": {}
}, ...]
}'
# Delete existing tenants
curl -X DELETE https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/tenants
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"idents": ["stripeince", ...]
}'
Bulk Role assignment
As you set the users in the system, in most cases, you'd want to assign them roles. It is also common to perform bulk role assignments when you decide to create a new type of role in the system and assign it in a workflow to a large number of users.
Another common use case is updating the resource roles of specific users to maintain a ReBAC relationship. While this can be done with a single request, the nature of a large-scale system would make it efficient to perform it as a bulk operation.
Permit support assignment and removal of roles in bulk using the following operations:
curl -X POST https://api.permit.io/v2/facts/{proj_id}/{env_id}/role_assignments/bulk \
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '[{
"user": "892179821739812389327",
"role": "admin",
"tenant": "default"
}, ...]'
curl -X DELETE https://api.permit.io/v2/facts/{proj_id}/{env_id}/role_assignments/bulk \
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '[{
"user": "892179821739812389327",
"role": "owner:892179821739812389327",
"tenant": "stripeince"
}, ...]'
Bulk Resource Operations
In a ReBAC policy, it is very important to keep your resource data in sync with the policy graph. While you can use the resource instance APIs to sync this data for a single request, it is more efficient to perform bulk operations on resources. In case you need to perform many such operations, we recommend using bulk resource operations.
The following bulk resource operations are supported:
# Update existing resource instances
curl -X PUT https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/resource_instances
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"operations": [{
"key": "react",
"resource": "repository",
"tenant": "default",
"attributes": {}
}
}, ...]
}'
# Delete existing resource instances
curl -X DELETE https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/resource_instances \
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"idents": ["repository:react", ...]
}'
Bulk Relationship Operations
Another aspect of such resource operations is the ability to maintain the nodes of a policy graph by editing the relationship tuples between resource instances. If you need to update a resource instance, it's recommended to do so in an event-driven manner using single requests. However, if you need to perform multiple operations, it's better to use bulk relationship operations.
The following bulk resource operations are supported:
# Create new relationships
curl -X POST https://api.permit.io/v2/facts/{proj_id}/{env_id}/relationship_tuples/bulk
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"operations": [{
"subject": "organization:permitio",
"relation": "owner",
"object": "repo:opal",
"tenant": "public"
}, ...]
}'
# Delete an existing relationships
curl -X DELETE https://api.permit.io/v2/facts/{proj_id}/{env_id}/relationship_tuples/bulk \
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"idents": [{
"subject": "organization:permitio",
"relation": "owner",
"object": "repo:removed_repo"
}, ...]
}'
Bulk role operations
Create roles
Create multiple roles in one request. You may create regular roles, as well as ReBAC resource roles for multiple resource in the same request. Pass the optional "resource" field to create a resource role. Roles created without the resource field will be created as regular (RBAC) roles. If the role exists, it will be updated.
curl -X PUT https://api.permit.io/v2/schema/{proj_id}/{env_id}/bulk/roles \
-H "Authorization: Bearer {your_permit_token}" \
-H "Content-Type: application/json" \
-d '{
"operations": [
{
"key": "admin",
"name": "Administrator",
"permissions": ["document:create", "document:delete"],
},
{
"key": "editor",
"name": "Editor",
"resource": "document"
"permissions": ["read", "write"],
}]
}'