Skip to main content
POST
/
v1
/
tenants
/
{tenant_id}
/
watch
go
cr, err := client.Watch.Watch(context.Background(), &v1.WatchRequest{
    TenantId:  "t1",
    SnapToken: "",
})
// handle stream response
for {
    res, err := cr.Recv()

    if err == io.EOF {
        break
    }

    // res.Changes
}
{
  "result": {
    "changes": {
      "snap_token": "<string>",
      "data_changes": [
        {
          "operation": "OPERATION_UNSPECIFIED",
          "tuple": {
            "entity": {
              "type": "<string>",
              "id": "<string>"
            },
            "relation": "<string>",
            "subject": {
              "type": "<string>",
              "id": "<string>",
              "relation": "<string>"
            }
          },
          "attribute": {
            "entity": {
              "type": "<string>",
              "id": "<string>"
            },
            "attribute": "<string>",
            "value": {
              "@type": "<string>"
            }
          }
        }
      ]
    }
  },
  "error": {
    "code": 123,
    "message": "<string>",
    "details": [
      {
        "@type": "<string>"
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://proxy-docs.permify.co/llms.txt

Use this file to discover all available pages before exploring further.

The Permify Watch API acts as a real-time broadcaster that shows changes in the relation tuples. The Watch API exclusively supports gRPC and works with PostgreSQL, given the track_commit_timestamp option is enabled. Please note, it doesn’t support in-memory databases or HTTP communication.

​
Requirements

  • PostgreSQL database set up with track_commit_timestamp option enabled

​
Enabling track_commit_timestamp on PostgreSQL

To ensure data consistency and synchronization between your application and Permify, enable track_commit_timestamp on your PostgreSQL server. This can be done by executing the following options in your PostgreSQL:

​
Option 1: SQL Command

  1. Open your PostgreSQL command line interface.
  2. Execute the following command: 
    ALTER SYSTEM SET track_commit_timestamp = ON;
  3. Reload the configuration with the following command: 
    SELECT pg_reload_conf();

​
Option 2: Editing postgresql.conf

  1. Find and open the postgresql.conf file in a text editor. Its location depends on your PostgreSQL installation. Common locations are:
    • Debian-based systems: /etc/postgresql/[version]/main/postgresql.conf
    • Red Hat-based systems: /var/lib/pgsql/data/postgresql.conf
  2. Add or modify the following line in the postgresql.conf file: 
    track_commit_timestamp = on
  3. Save and close the postgresql.conf file.
  4. Reload the PostgreSQL configuration for the changes to take effect. This can be done via the PostgreSQL console: 
    SELECT pg_reload_conf();
    Or if you have command line access, use: 
    sudo service postgresql reload
Please ensure you have the necessary permissions to execute these commands or modify the postgresql.conf file. Also, remember that changes in the postgresql.conf file will persist across restarts, while the SQL method may need to be reapplied depending on your PostgreSQL version and setup.
Important Configuration Requirement: To use the Watch API, it must be enabled in your configuration file. Add or modify the following lines:
service:
  watch:
    enabled: true
For performance guidance, scaling strategies, and reconnection best practices, see Watch — Operations.

Path Parameters

​
tenant_id
string
required

Identifier of the tenant, if you are not using multi-tenancy (have only one tenant) use pre-inserted tenant t1 for this field. Required, and must match the pattern \“[a-zA-Z0-9-,]+\“, max 64 bytes.

Body

application/json

WatchRequest is the request message for the Watch RPC. It contains the details needed to establish a watch stream.

​
snap_token
string

The snap token to avoid stale cache, see more details on Snap Tokens.

Response

A successful response.(streaming responses)

​
result
object

WatchResponse is the response message for the Watch RPC. It contains the changes in the data that are being watched.

​
error
object