Skip to main content
A bundle is a named, parameterised template that describes which relationships and attributes should be created or deleted when a specific action occurs in your application. Instead of calling the Write Data API with hand-crafted tuples on every event, you define the template once and execute it by name with the relevant identifiers.

​
Why use bundles

Without bundles, every service that needs to write authorization data must know the exact tuple structure. If that structure changes — a new relation is added, a naming convention shifts — every service must be updated. Bundles centralise that logic. The authorization model and the data-write templates live together in Permify, and your application services only need to call RunBundle with a name and a set of identifiers.

​
Defining a bundle

Use the Write Bundle API to create or update a bundle. Each bundle has:
  • A unique name used to identify and execute it.
  • An arguments list declaring the variable names the bundle accepts.
  • An operations list describing the relationships and attributes to write or delete, using {{.variableName}} template syntax.
{
  "bundles": [
    {
      "name": "organization_created",
      "arguments": [
        "creatorID",
        "organizationID"
      ],
      "operations": [
        {
          "relationships_write": [
            "organization:{{.organizationID}}#admin@user:{{.creatorID}}",
            "organization:{{.organizationID}}#manager@user:{{.creatorID}}"
          ],
          "attributes_write": [
            "organization:{{.organizationID}}$public|boolean:false"
          ]
        }
      ]
    }
  ]
}
This bundle declares that whenever an organization is created, Permify should:
  1. Write organization:{organizationID}#admin@user:{creatorID}
  2. Write organization:{organizationID}#manager@user:{creatorID}
  3. Set the attribute organization:{organizationID}$public to false

​
Running a bundle

Use the Run Bundle API to execute a bundle by name, passing the concrete argument values. 
{
  "name": "organization_created",
  "arguments": {
    "creatorID": "564",
    "organizationID": "789"
  }
}
Permify substitutes the arguments into the template and atomically writes the resulting data. For this example, the following entries are created:
  • organization:789#admin@user:564
  • organization:789#manager@user:564
  • organization:789$public|boolean:false
RunBundle returns a snap_token representing the database state after the write. Use that token in subsequent check requests to guarantee fresh results. See Snap Tokens.

​
Operations

Each object in the operations array supports four keys:
KeyDescription
relationships_writeRelationships to create. Uses tuple notation: entity_type:id#relation@subject_type:id.
relationships_deleteRelationships to delete. Same notation as relationships_write.
attributes_writeAttributes to set. Uses attribute notation: entity_type:id$attribute|type:value.
attributes_deleteAttributes to remove. Same notation as attributes_write.

​
Bundle API endpoints

Write Bundle

Create or update one or more bundles.

Run Bundle

Execute a bundle with concrete argument values.

Read Bundle

Retrieve the definition of a bundle by name.

Build docs developers (and LLMs) love

Get started for freeTalk to us