Skip to main content
POST /v1/tenants/{tenant_id}/watch The Watch API establishes a long-lived server-streaming connection and pushes DataChanges events to the client whenever relationship tuples or attributes are written or deleted for the tenant. This is useful for keeping downstream caches, search indexes, or audit logs in sync with Permify’s authorization data.
The Watch API only supports gRPC (port 3478). It does not support HTTP/REST. It also requires PostgreSQL as the database backend with track_commit_timestamp enabled — it does not work with in-memory storage.

​
Requirements

  • PostgreSQL database with track_commit_timestamp = on
  • Watch service enabled in the Permify configuration:
service:
  watch:
    enabled: true

​
Enable track_commit_timestamp

Run the following SQL on your PostgreSQL instance: 
ALTER SYSTEM SET track_commit_timestamp = ON;
SELECT pg_reload_conf();
Or add to postgresql.conf: 
track_commit_timestamp = on
Then reload PostgreSQL: 
sudo service postgresql reload

​
Path Parameters

​
tenant_id
string
required
The tenant identifier. Use t1 for single-tenant deployments. Must match ^([a-zA-Z0-9_\-@\.:+]{1,128}|\*)$.

​
Request Body

​
snap_token
string
Optional snap token indicating the point in the change stream to start from. Leave empty to receive all new changes going forward.

​
Response (streaming)

Each streamed message has the following structure:
​
changes
object
A DataChanges object describing one or more changes applied in a single transaction.

​
Example (gRPC — Go)

cr, err := client.Watch.Watch(context.Background(), &v1.WatchRequest{
    TenantId:  "t1",
    SnapToken: "",
})

for {
    res, err := cr.Recv()

    if err == io.EOF {
        break
    }

    // res.Changes contains the DataChanges for this event
}

​
Error Codes

gRPC StatusDescription
INVALID_ARGUMENTMissing or invalid request fields
UNAUTHENTICATEDMissing or invalid credentials
NOT_FOUNDTenant not found
UNAVAILABLEWatch service is disabled or PostgreSQL is not configured correctly
INTERNALInternal server error
For performance guidance, reconnection strategies, and scaling considerations, see Watch — Operations.

Build docs developers (and LLMs) love

Get started for freeTalk to us