Bulk user and relationship tuple requests with the Node.js SDK

The Node.js SDK wraps the Permit API bulk endpoints for users and relationship tuples, so one call creates, replaces, or deletes many items. This reference is for backend developers who sync many users or relationships at once, for example during an initial import. For item limits per call and bulk endpoints for tenants, resource instances, role assignments, and roles, see Perform bulk operations.

Prerequisites

• A permit client created with an API key for the environment. See Create a Permit client.
• For the HTTP samples: your project ID and environment ID. See Get the project ID and environment ID.

Bulk methods in the Node.js SDK

Method	Signature	Permit API endpoint
permit.api.users.bulkUserCreate	bulkUserCreate(users: UserCreate[])	POST /v2/facts/{proj_id}/{env_id}/bulk/users
permit.api.users.bulkUserReplace	bulkUserReplace(users: UserCreate[])	PUT /v2/facts/{proj_id}/{env_id}/bulk/users
permit.api.users.bulkUserDelete	bulkUserDelete(userKeys: string[])	DELETE /v2/facts/{proj_id}/{env_id}/bulk/users
permit.api.relationshipTuples.bulkRelationshipTuples	bulkRelationshipTuples(tuples: RelationshipTupleCreate[])	POST /v2/facts/{proj_id}/{env_id}/relationship_tuples/bulk
permit.api.relationshipTuples.bulkUnRelationshipTuples	bulkUnRelationshipTuples(tuples: RelationshipTupleDelete[])	DELETE /v2/facts/{proj_id}/{env_id}/relationship_tuples/bulk

Each method wraps the array in the request body that the endpoint expects (operations for create and replace, idents for delete) and resolves to the response body of the endpoint.

If the Permit API returns an error status code, each method throws a PermitApiError. If the configured API context doesn't match the environment-level endpoint, each method throws a PermitContextError.

Each bulk endpoint answers a successful request with an empty JSON object ({}), so the response body doesn't report per-item results. To confirm what a bulk call changed, read the items back, for example with permit.api.users.list(), or open the Directory screen in the Permit dashboard.

Each SDK example in the following sections calls await inside an async function, with the permit client from the prerequisites. The HTTP sample after each SDK example shows the request body of the endpoint that the method calls. In each HTTP sample, replace {proj_id} and {env_id} with your project and environment IDs or keys, and API_SECRET_KEY with your API key.

Bulk create relationship tuples

bulkRelationshipTuples() creates many relationship tuples in one request. Each item in the operations array is a RelationshipTupleCreate object:

Field	Required	Description
subject	Yes	Subject resource instance, in the format resource_type:instance_key, for example folder:budget23.
relation	Yes	Key of the relation.
object	Yes	Object resource instance, in the format resource_type:instance_key.
tenant	No	Key of the tenant of the subject and object. Required when neither the subject nor the object instance exists.

await permit.api.relationshipTuples.bulkRelationshipTuples([
  { subject: 'folder:folder-1', relation: 'parent', object: 'file:file-1', tenant: 'default' },
]);

The same request as an HTTP call:

curl -X POST 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/relationship_tuples/bulk' \
  -H 'Authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "operations": [
          { "subject": "folder:folder-1", "relation": "parent", "object": "file:file-1", "tenant": "default" }
        ]
      }'

Bulk delete relationship tuples

bulkUnRelationshipTuples() deletes many relationship tuples in one request. Each item in the idents array is a RelationshipTupleDelete object with the required fields subject, relation, and object, in the same formats as for creation.

await permit.api.relationshipTuples.bulkUnRelationshipTuples([
  { subject: 'folder:folder-1', relation: 'parent', object: 'file:file-2' },
]);

The same request as an HTTP call:

curl -X DELETE 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/relationship_tuples/bulk' \
  -H 'Authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "idents": [
          { "subject": "folder:folder-1", "relation": "parent", "object": "file:file-2" }
        ]
      }'

Bulk create users

bulkUserCreate() creates many users in one request. Each item in the operations array is a UserCreate object with a required key and the optional fields email, first_name, last_name, attributes, and role_assignments. See Create a user with the Node.js SDK for the field descriptions.

await permit.api.users.bulkUserCreate([
  { key: 'user-1', email: 'user1@example.com', first_name: 'Ada', last_name: 'Example' },
  { key: 'user-2', email: 'user2@example.com' },
]);

The same request as an HTTP call:

curl -X POST 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/users' \
  -H 'Authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "operations": [
          { "key": "user-1", "email": "user1@example.com", "first_name": "Ada", "last_name": "Example", "attributes": {} },
          { "key": "user-2", "email": "user2@example.com", "attributes": {} }
        ]
      }'

Bulk replace users

bulkUserReplace() replaces the data of many users in one request, for example their email or first name. The user key identifies each user and can't change. Each item in the operations array is a UserCreate object.

await permit.api.users.bulkUserReplace([
  { key: 'user-1', email: 'ada@example.com', first_name: 'Ada', last_name: 'Example' },
  { key: 'user-2', email: 'grace@example.com' },
]);

The same request as an HTTP call:

curl -X PUT 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/users' \
  -H 'Authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "operations": [
          { "key": "user-1", "email": "user1@example.com", "first_name": "Ada", "last_name": "Example", "attributes": {} },
          { "key": "user-2", "email": "user2@example.com", "attributes": {} }
        ]
      }'

Bulk delete users

bulkUserDelete() deletes many users in one request. Each string in the idents array is the key or ID of a user to delete.

await permit.api.users.bulkUserDelete(['user-1', 'user-2']);

The same request as an HTTP call:

curl -X DELETE 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/users' \
  -H 'Authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "idents": ["user-1", "user-2"] }'

Errors from bulk methods

Error	Cause
PermitApiError	The Permit API returned an error status code, for example because the request has more items than the per-call limit. See Bulk limits.
PermitContextError	The API context configured in the SDK client doesn't match the environment-level context that the endpoint requires.

Related pages

• Perform bulk operations
• Sync a user with the Node.js SDK
• List relationship tuples with the Node.js SDK