Skip to main content
Permify offers various options for configuring your Permify Server. Here is the example configuration YAML file with glossary below. You can also find this example config file in Permify repo.

Configure Using Flags

Alternatively, you can set configuration options using flags when running the command. See all the configuration flags by running,

Configuration Using YAML File

Configuration Glossary

Definition

Server options to run Permify. (grpc and http available for now.)

Structure

Glossary

ENV

Definition

Real time logs of authorization. Permify uses zerolog as a logger.

Structure

Glossary

ENV

Definition

You can choose to authenticate users to interact with Permify API.There are 2 authentication method you can choose:
  • Pre Shared Keys
  • OpenID Connect

Pre Shared Keys

On this method, you must provide a pre shared keys in order to identify yourself.

Structure

Glossary

ENV

OpenID Connect

Permify supports OpenID Connect (OIDC). OIDC provides an identity layer on top of OAuth 2.0 to address the shortcomings of using OAuth 2.0 for establishing identity.With this authentication method, you be able to integrate your existing Identity Provider (IDP) to validate JSON Web Tokens (JWTs) using JSON Web Keys (JWKs). By doing so, only trusted tokens from the IDP will be accepted for authentication.

Structure

Glossary

ENV

Definition

Permify integrated with jaeger, otlp, signoz, and zipkin tacing tools to analyze performance and behavior of your authorization when using Permify.

Structure

Glossary

ENV

Definition

Configuration for observing metrics; check count, cache check count and session information; Permify version, hostname, os, arch.

Structure

Glossary

ENV

Definition

Configurations for the database that points out where your want to store your authorization data (relation tuples, audits, decision logs, authorization model)

Structure

Glossary

ENV

Production Best Practices: Connection Pooling with pgcat

For production deployments, especially when running multiple Permify instances, we strongly recommend using pgcat (PostgreSQL Connection Pooler) for server-side connection pooling. This helps manage database connections efficiently and prevents connection exhaustion.For detailed information about pgcat setup, configuration, and best practices, see the Database Pooling with Pgcat guide.Why use pgcat?
  • Connection Management: pgcat manages a pool of connections to PostgreSQL, allowing multiple Permify instances to share connections efficiently
  • Performance: Reduces connection overhead and improves query performance
Configuration ExampleWhen using pgcat with session mode, configure Permify to connect through pgcat instead of directly to PostgreSQL:
Key Points:
  • Point your uri, writer.uri, and reader.uri to pgcat (typically on port 6432) instead of PostgreSQL directly
  • Set max_connections to a low value since pgcat manages the actual connection pool
  • For session mode with pgcat, set min_connections to 0 to allow the pool to shrink when not needed
  • Configure connection lifecycle settings to help with connection cycling and prevent connection exhaustion

Definition

Configurations for the permify service and how it should behave. You can configure the circuit breaker pattern, configuration watcher, and service specific options for permission and schema services (rate limiting, concurrency limiting, cache size).

Structure

Glossary

ENV

Definition

pprof is a performance profiler for Go programs. It allows developers to analyze and understand the performance characteristics of their code by generating detailed profiles of program executionWhen enabled, Permify exposes Go’s standard pprof HTTP endpoints on the configured port (default 6060):You can analyse captured profiles locally using Go’s built-in tooling:
When to enable the profiler:
  • Investigating a CPU spike or unexpectedly high latency in Permify.
  • During load or capacity testing to identify bottlenecks before production.
  • When suspecting a performance regression after a version upgrade.
Best practice: Enable the profiler temporarily when needed, then disable it again. Keeping it permanently open in production is not recommended — it exposes an unauthenticated HTTP endpoint and adds a small constant overhead.
The pprof endpoint has no built-in authentication. Restrict network access to it (e.g. via a sidecar, internal network policy, or firewall rule) so it is not reachable from the public internet.

Structure

Glossary

ENV

Definition

A consistent hashing ring ensures data distribution that minimizes reorganization when nodes are added or removed, improving scalability and performance in distributed systems.”

Structure

Glossary

ENV