Syncing Data

Permify stores your authorization data in the database of your choice, which serves as the single source of truth for all permission checks. You write this data through the Permify API, and it is queried automatically when you call the Check API or any lookup endpoint. Authorization data in Permify takes two forms: relationships and attributes.

Relationships

Relationships are the core of Permify’s data model. They build up a collection of Access Control Lists (ACLs) called relational tuples. Each relational tuple represents a fact: user U has relation R to object O. The simplest form is:

entity # relation @ subject

For example:

Tuple	Meaning
`organization:1#admin@user:3`	User 3 is an admin of organization 1
`document:1#owner@user:1`	User 1 owns document 1
`document:1#maintainer@organization:2#member`	All members of organization 2 are maintainers of document 1

The relation field in the subject object controls what the subject refers to:

Empty ("") — the subject is a direct individual user (e.g. user:123).
"..." — the subject is the entity itself without a sub-relation. Used when the subject type is not the user entity.
A named relation (e.g. "member") — the subject is a userset: everyone who holds that relation on the subject entity.

Attributes

For scenarios where relationships alone are not enough — such as geo-based restrictions, time-based access, or boolean flags — Permify supports attributes. Attributes attach typed values to entities:

subject $ attribute | value

Examples:

Attribute	Meaning
`account:1$balance\|double:4000`	Account 1’s balance is 4000
`post:546$is_restricted\|boolean:true`	Post 546 is marked as restricted
`user:122$regions\|string[]:US,MEX`	User 122 is associated with the US and Mexico regions

Writing authorization data

Relationships and attributes are created via the Write Data API at runtime — typically when a user action in your application changes the authorization state (e.g. a user creates a document, joins an organization, or is granted a role). All data must conform to your authorization schema.

Write Data API

POST /v1/tenants/{tenant_id}/data/write Consider this schema for the examples below:

entity user {}

entity organization {

    relation admin  @user
    relation member @user

}

entity document {

    relation owner      @user
    relation parent     @organization
    relation maintainer @user @organization#member

    action view   = owner or parent.member or maintainer or parent.admin
    action edit   = owner or maintainer or parent.admin
    action delete = owner or parent.admin
}

Example: document owner

When user:1 creates document:2, write the ownership tuple document:2#owner@user:1:

cURL
Go
Node

curl --location --request POST 'localhost:3476/v1/tenants/t1/data/write' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata": {
    "schema_version": ""
  },
  "tuples": [
    {
      "entity": {
        "type": "document",
        "id": "2"
      },
      "relation": "owner",
      "subject": {
        "type": "user",
        "id": "1",
        "relation": ""
      }
    }
  ]
}'

rr, err := client.Data.Write(context.Background(), &v1.DataWriteRequest{
    TenantId: "t1",
    Metadata: &v1.DataWriteRequestMetadata{
        SchemaVersion: "",
    },
    Tuples: []*v1.Tuple{
        {
            Entity: &v1.Entity{
                Type: "document",
                Id:   "2",
            },
            Relation: "owner",
            Subject: &v1.Subject{
                Type: "user",
                Id:   "1",
            },
        },
    },
})

client.data.write({
    tenantId: "t1",
    metadata: {
        schemaVersion: ""
    },
    tuples: [{
        entity: {
            type: "document",
            id: "2"
        },
        relation: "owner",
        subject: {
            type: "user",
            id: "1"
        }
    }]
}).then((response) => {
    // handle response
})

Example: organization admin

Relational tuple: organization:1#admin@user:3 — User 3 is an admin of organization 1.

cURL
Go
Node

curl --location --request POST 'localhost:3476/v1/tenants/t1/data/write' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata": {
    "schema_version": ""
  },
  "tuples": [
    {
      "entity": {
        "type": "organization",
        "id": "1"
      },
      "relation": "admin",
      "subject": {
        "type": "user",
        "id": "3",
        "relation": ""
      }
    }
  ]
}'

rr, err := client.Data.Write(context.Background(), &v1.DataWriteRequest{
    TenantId: "t1",
    Metadata: &v1.DataWriteRequestMetadata{
        SchemaVersion: "",
    },
    Tuples: []*v1.Tuple{
        {
            Entity: &v1.Entity{
                Type: "organization",
                Id:   "1",
            },
            Relation: "admin",
            Subject: &v1.Subject{
                Type: "user",
                Id:   "3",
            },
        },
    },
})

client.data.write({
    tenantId: "t1",
    metadata: {
        schemaVersion: ""
    },
    tuples: [{
        entity: {
            type: "organization",
            id: "1"
        },
        relation: "admin",
        subject: {
            type: "user",
            id: "3"
        }
    }]
}).then((response) => {
    // handle response
})

Example: parent organization

Relational tuple: document:1#parent@organization:1#... — Organization 1 is the parent of document 1.

cURL
Go
Node

curl --location --request POST 'localhost:3476/v1/tenants/t1/data/write' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata": {
    "schema_version": ""
  },
  "tuples": [
    {
      "entity": {
        "type": "document",
        "id": "1"
      },
      "relation": "parent",
      "subject": {
        "type": "organization",
        "id": "1",
        "relation": "..."
      }
    }
  ]
}'

rr, err := client.Data.Write(context.Background(), &v1.DataWriteRequest{
    TenantId: "t1",
    Metadata: &v1.DataWriteRequestMetadata{
        SchemaVersion: "",
    },
    Tuples: []*v1.Tuple{
        {
            Entity: &v1.Entity{
                Type: "document",
                Id:   "1",
            },
            Relation: "parent",
            Subject: &v1.Subject{
                Type:     "organization",
                Id:       "1",
                Relation: "...",
            },
        },
    },
})

client.data.write({
    tenantId: "t1",
    metadata: {
        schemaVersion: ""
    },
    tuples: [{
        entity: {
            type: "document",
            id: "1"
        },
        relation: "parent",
        subject: {
            type: "organization",
            id: "1",
            relation: "..."
        }
    }]
}).then((response) => {
    // handle response
})

Example: group-based maintainer

Relational tuple: document:1#maintainer@organization:2#member — All members of organization 2 are maintainers of document 1.

cURL
Go
Node

curl --location --request POST 'localhost:3476/v1/tenants/t1/data/write' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata": {
    "schema_version": ""
  },
  "tuples": [
    {
      "entity": {
        "type": "document",
        "id": "1"
      },
      "relation": "maintainer",
      "subject": {
        "type": "organization",
        "id": "2",
        "relation": "member"
      }
    }
  ]
}'

rr, err := client.Data.Write(context.Background(), &v1.DataWriteRequest{
    TenantId: "t1",
    Metadata: &v1.DataWriteRequestMetadata{
        SchemaVersion: "",
    },
    Tuples: []*v1.Tuple{
        {
            Entity: &v1.Entity{
                Type: "document",
                Id:   "1",
            },
            Relation: "maintainer",
            Subject: &v1.Subject{
                Type:     "organization",
                Id:       "2",
                Relation: "member",
            },
        },
    },
})

client.data.write({
    tenantId: "t1",
    metadata: {
        schemaVersion: ""
    },
    tuples: [{
        entity: {
            type: "document",
            id: "1"
        },
        relation: "maintainer",
        subject: {
            type: "organization",
            id: "2",
            relation: "member"
        }
    }]
}).then((response) => {
    // handle response
})

Snap tokens

Every Write Data response includes a snap_token:

{
  "snap_token": "FxHhb4CrLBc="
}

A snap token encodes the timestamp of a write operation. Pass it in subsequent check requests to guarantee that the permission engine reads data at least as fresh as that write — preventing stale reads in distributed deployments.

{
  "metadata": {
    "snap_token": "FxHhb4CrLBc="
  },
  ...
}

See Snap Tokens for more details.

Audit logs and history

Permify uses MVCC (Multi-Version Concurrency Control) to maintain a complete history of all permission data changes. This provides a built-in audit trail — you can review what changed, who changed it, and when.

Historical review — query past versions of your permission state.
Current state review — inspect the latest version of any permission setting.
Garbage collection — a built-in GC process cleans up old versions to keep storage optimized. Configure it via the database.garbage_collection settings in your config file.

Overview

Getting Started

Modeling Guides

Deployment & Configuration

Operations

Use Cases

Relationships

Attributes

Writing authorization data

Write Data API

Example: document owner

Example: organization admin

Example: parent organization

Example: group-based maintainer

Snap tokens

Audit logs and history

Build docs developers (and LLMs) love

Overview

Getting Started

Modeling Guides

Deployment & Configuration

Operations

Use Cases

Documentation Index

​Relationships

​Attributes

​Writing authorization data

​Write Data API

​Example: document owner

​Example: organization admin

​Example: parent organization

​Example: group-based maintainer

​Snap tokens

​Audit logs and history

Build docs developers (and LLMs) love

Relationships

Attributes

Writing authorization data

Write Data API

Example: document owner

Example: organization admin

Example: parent organization

Example: group-based maintainer

Snap tokens

Audit logs and history