system:permify@en

Ecosystem

Permify

An open-source authorization service modelled on Zanzibar, now owned by FusionAuth and licensed under AGPL-3.0, with a schema language, snap tokens and a PostgreSQL datastore.

Facts checked on Paper sections §2.1, §2.2, §2.3.1, §2.4, §3.2.4

Maintainer
FusionAuth (acquisition announced 2025-11-20)
License
AGPL-3.0 (Apache-2.0 until 2025-05-12)
Language
Go
Status
Active
Latest release
v1.7.6 (2026-11-05)
Repository
github.com/Permify/permify
Documentation
fusionauth.io/permify-docs

Permify is an authorization service written in Go. Its documentation calls it “an open-source authorization service for creating fine-grained and scalable authorization systems”, “inspired by Google’s consistent, global authorization system, Google Zanzibar” (Permify docs). You describe entity types and their relations in the Permify Schema, write relationships as tuples, and ask a server over gRPC or HTTP whether a subject has a permission.

FusionAuth’s acquisition of Permify was announced on 2025-11-20 (Permify announcement, FusionAuth announcement). FusionAuth now names the product “FusionAuth FGA by Permify” (FusionAuth support post), and the documentation lives at fusionauth.io/permify-docs. The Permify post states that “The core Permify project remains open source and will continue to live on GitHub.”

Paper and Permify side by side

Each row names a concept from the paper and the closest thing Permify documents. Where Permify has nothing comparable, the cell says so.

In the paper In Permify
Namespace config (§2.3) An entity block in the Permify Schema, with relation, permission (or its synonym action), attribute and rule (modeling)
Relation tuple object#relation@user (§2.1) Relational tuple entity#relation@subject, for example doc:readme#owner@user:anne (storing data)
_this The stored tuples of a relation; a permission includes them by naming the relation
computed_userset Naming another relation or permission of the same entity, as edit inside view = viewer or edit
tuple_to_userset Dot traversal through a relation, as parent.view
Union, intersection, exclusion or, and, not
Zookie (§2.2, §2.4) Snap token, the snap_token field (snap tokens)
Check (§2.4.4) Permission.Check, plus BulkCheck (service.proto)
Read (§2.4.1) Data.ReadRelationships, plus ReadAttributes
Write (§2.4.2) Data.Write, WriteRelationships, Delete, DeleteRelationships
Watch (§2.4.3) Watch.Watch, a server stream (Watch operations)
Expand (§2.4.5) Permission.Expand
Leopard (§3.2.4) No equivalent documented
Spanner (§3.1) PostgreSQL, or an in-memory engine (the configuration default) (configuration)

Permify also has lookup calls the paper does not describe: LookupEntity, LookupSubject and SubjectPermission.

The running example in Permify Schema

The paper’s Figure 1 gives documents three concentric relations: owners are editors, editors are viewers, and viewers of the parent folder are viewers of the document (§2.3.1). Here is that model with the running example’s types, in Permify Schema.

entity user {}

entity group {
    relation member @user
}

entity folder {
    relation viewer @user @group#member

    permission view = viewer
}

entity doc {
    relation parent @folder
    relation owner @user
    relation editor @user @group#member
    relation viewer @user @group#member

    permission edit = owner or editor
    permission view = viewer or edit or parent.view
}

@group#member lets a relation hold a userset: “everyone who is a member of this group”. parent.view follows the parent relation to the folder and evaluates the folder’s view permission there; the docs state that “The same traversal rule applies to both relation.userset and relation.permission” (modeling).

The running example is five tuples:

doc:readme#owner@user:anne
group:eng#member@user:beto
doc:readme#viewer@group:eng#member
doc:readme#parent@folder:A
folder:A#viewer@user:chen

Which stored tuples and which rules give each of the three people access to the readme?

The running example as Permify relationshipsFive relationships. user:anne is owner of doc:readme. user:beto is member of group:eng. group:eng#member is viewer of doc:readme. folder:A is parent of doc:readme. user:chen is viewer of folder:A. The path from Chen through folder A to the readme is highlighted: it is resolved by the rule parent.view.user:anneuser:betouser:chengroup:engfolder:Adoc:readmeownermemberviewer (#member)viewerparent
Anne views through owner → edit → view, Beto through the group userset, Chen through parent.view. Dashed: a userset, not a single user.

Notice that the arrow from folder:A to the readme is a stored tuple (doc:readme#parent@folder:A), while the step from Chen’s folder access to the readme is not stored anywhere: the schema’s parent.view computes it at check time, as tuple_to_userset does in the paper.

Architecture

How do Permify servers share work, and where do tuples live?

Permify deployment, as described in the docsA service calls Permify pods over gRPC on port 3478 or HTTP on port 3476. In distributed mode the pods form a consistent-hash ring, so a request hashed to pod 2 is answered from pod 2's local Ristretto cache. Both pods read and write PostgreSQL, which may be configured with separate writer and reader connections. A Watch consumer holds a stream to one pod.Your serviceWatch consumerPermify pod 1local cachePermify pod 2local cachePostgreSQLwriter + readerCheck, Writehash ringSQLSQLWatch stream
Yellow: Permify servers. Green: the datastore. Blue: clients. The ring is optional (distributed mode).

The pieces, each from the docs:

  • Servers listen on HTTP port 3476 and gRPC port 3478 by default (configuration). The database section accepts separate writer and reader URIs.
  • Each pod keeps a process-local Ristretto cache of check results; “there is no shared cache layer” (cache).
  • With distributed.enabled, the pods hash each request onto a consistent-hash ring, so “subsequent API calls with the same hash will retrieve the response from the instance 2, regardless of which instance that API called from”. A circuit breaker stops calls to the database while it is down.
  • PostgreSQL stores tuples with MVCC: Permify creates “a separate database snapshot for each write and delete operation”, and an optional garbage collector deletes old versions.
  • Each Watch stream “opens a long-lived connection with a continuous polling loop against the database” (Watch operations).

Consistency

Permify’s snap token plays the zookie’s part. A Write returns it; the client stores it with the resource and sends it back as snap_token on later checks. The docs describe it as “a token that consists of an encoded timestamp”, compared in access checks “to ensure that the snapshot of the access control is at least as fresh as the resource timestamp” (snap tokens). That is the paper’s guarantee for a check carrying a zookie: “a consistent snapshot no earlier than” the given zookie (§2.4.4).

How does a check made after a sharing change see that change?

Snap token round tripThe service writes the tuple doc:readme#viewer@group:eng#member. Permify records it in a new transaction in PostgreSQL and returns a snap token. The service stores the token with the readme. A later check for Beto on the readme sends the token, and Permify evaluates the check at a snapshot no older than the token, so the new viewer tuple is visible.timeYour servicePermifyPostgreSQLsnap_tokenWrite: eng#memberviews readmeData.Writenew transactionrecordedreturnssnap_tokenstore tokenwith the readmeCheck beto view+ snap_tokensnapshot no olderthan the token
The token travels with the content, as the paper's zookie does (§2.2).

Notice the behaviour without a token. The paper lets Zanzibar “choose a reasonably recent snapshot, possibly offering a lower-latency response” (§2.4.1). Permify instead reads the ID of the latest transaction from its transactions table and evaluates at that snapshot; the result is cached under a key that contains that ID (snap tokens). The cache key is check_{tenant_id}_{schema_version}:{snapshot_token}:{check_request} (cache), so a new write produces new keys rather than invalidating old ones.

Differences from the paper

  • Attributes and rules. Permify Schema adds attribute and rule for attribute-based checks, such as permission view = check_ip_range(ip_range) or admin (modeling). Zanzibar’s rewrites work on tuples only (§2.3.1).
  • Contextual tuples. Relations “dynamically added to permission request operations” are evaluated with the stored ones and never written (contextual tuples).
  • Tenants. A Tenancy service creates, lists and deletes tenants (service.proto); the paper has no tenant concept.
  • Storage. PostgreSQL with MVCC snapshots, instead of Spanner, whose TrueTime mechanism timestamps every ACL write (§2.2, §3.1). The distributed cache works “across availability zones (within an AWS region)” (cache).
  • No denormalized index. The paper answers deeply nested group checks with Leopard (§3.2.4). Permify documents result caching and consistent hashing, not a set index.
  • Lookups. LookupEntity and LookupSubject answer “which resources” and “which subjects” questions that the paper’s API does not cover.

Status

  • First release v0.0.0-alpha1 on 2022-08-03; latest v1.7.6 on 2026-11-05; last commit to the default branch on 2026-11-10; about 6.0k stars (releases, GitHub API, 2026-11-13).
  • License: the LICENSE file was replaced with the Apache-2.0 text on 2023-02-14 (commit 97285f9) and with the AGPL-3.0 text on 2025-05-12, in a commit titled “docs: update license” (commit 26912d9). Before that, in 2022, the file held Apache-2.0 text (2022-07-14), then GPL-3.0 (2022-08-25), then AGPL-3.0 (2022-08-26) (LICENSE history).
  • Ownership: acquired by FusionAuth, announced 2025-11-20 on the Permify blog (post); the FusionAuth announcement page shows no date (post). Both are vendor-authored.
  • Documentation moved from docs.permify.co to fusionauth.io/permify-docs.

Sources