permify/docs/setting-up/configuration.mdx at fcac8d19d756077c4cb10d78ed9b9b8fca52b628 · Permify/permify

title	Configuration
icon	gear

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,

docker run -p 3476:3476 -p 3478:3478 ghcr.io/permify/permify --help

Configuration Using YAML File

# The server section specifies the HTTP and gRPC server settings,
# including whether or not TLS is enabled and the certificate and
# key file locations.
server:
  host: ""
  rate_limit: 100
  http:
    enabled: true
    port: 3476
    grpc_target_host: 127.0.0.1
    tls:
      enabled: true
      cert: /etc/letsencrypt/live/yourdomain.com/fullchain.pem
      key: /etc/letsencrypt/live/yourdomain.com/privkey.pem
  grpc:
    port: 3478
    tls:
      enabled: true
      cert: /etc/letsencrypt/live/yourdomain.com/fullchain.pem
      key: /etc/letsencrypt/live/yourdomain.com/privkey.pem

# The logger section sets the logging level for the service.
logger:
  level: info

# The profiler section enables or disables the pprof profiler and
# sets the port number for the profiler endpoint.
profiler:
  enabled: true
  port: 6060

# The authn section specifies the authentication method for the service.
authn:
  enabled: true
  method: preshared
  preshared:
    keys: [ ]

# The tracer section enables or disables distributed tracing and sets the
# exporter and endpoint for the tracing data.
tracer:
  exporter: zipkin
  endpoint: http://localhost:9411/api/v2/spans
  enabled: true

# The meter section enables or disables metrics collection and sets the
# exporter and endpoint for the collected metrics.
meter:
  exporter: otlp
  endpoint: localhost:4318
  enabled: true

# The service section sets various service-level settings, including whether
# or not to use a circuit breaker, and cache sizes for schema, permission,
# and relationship data.
service:
  circuit_breaker: false
  watch:
    enabled: false
  schema:
    cache:
      number_of_counters: 1_000
      max_cost: 10MiB
  permission:
    bulk_limit: 100
    concurrency_limit: 100
    cache:
      number_of_counters: 10_000
      max_cost: 10MiB

# The database section specifies the database engine and connection settings,
# including the URI for the database, whether or not to auto-migrate the database,
# and connection pool settings.
database:
  engine: postgres
  uri: postgres://user:password@host:5432/db_name
  auto_migrate: false
  max_connections: 20  # Maximum number of connections in the pool (maps to pgxpool MaxConns)
  max_open_connections: 20  # Deprecated: use max_connections instead. Kept for backward compatibility.
  max_idle_connections: 1  # Deprecated: use min_connections instead. Kept for backward compatibility (maps to MinConnections if min_connections is not set).
  min_connections: 0  # Minimum number of connections in the pool (maps to pgxpool MinConns). If 0 and max_idle_connections is set, max_idle_connections will be used.
  min_idle_connections: 0  # Minimum idle connections (maps to pgxpool MinIdleConns). Must be explicitly set if needed (not set in old code).
  max_connection_lifetime: 300s
  max_connection_idle_time: 60s
  health_check_period: 0s  # Use pgxpool default (1 minute) if 0
  max_connection_lifetime_jitter: 0s  # Will default to 20% of max_connection_lifetime if 0
  connect_timeout: 0s  # Use pgx default (no timeout) if 0
  garbage_collection:
    enabled: true
    interval: 200h
    window: 200h
    timeout: 5m

# distributed configuration settings
distributed:
  # Indicates whether the distributed mode is enabled or not
  enabled: true

  # The address of the distributed service.
  # Using a Kubernetes DNS name suggests this service runs in a Kubernetes cluster
  # under the 'default' namespace and is named 'permify'
  address: "kubernetes:///permify.default"

  # The port on which the service is exposed
  port: "5000"

Configuration Glossary

Definition

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

Structure

├── server
    ├── host
    ├── rate_limit
    ├── (`grpc` or `http`)
    │   ├── enabled
    │   ├── port
    │   ├── grpc_target_host
    │   └── tls
    │       ├── enabled
    │       ├── cert
    │       └── key

Glossary

Required	Argument	Default	Description
[ ]	host	""	host/interface to bind the HTTP server.
[ ]	rate_limit	100	the maximum number of requests the server should handle per second.
[x]	[ server_type ]	-	server option type can either be `grpc` or `http`.
[ ]	enabled (for server type)	true	switch option for server.
[x]	port	-	port that server run on.
[ ]	grpc_target_host (HTTP)	127.0.0.1	host the HTTP gateway uses to connect to the local gRPC server.
[x]	tls	-	transport layer security options.
[ ]	enabled (for tls)	false	switch option for tls
[ ]	cert	-	tls certificate path.
[ ]	key	-	tls key path

ENV

Argument	ENV	Type
server-host	PERMIFY_SERVER_HOST	string
rate_limit	PERMIFY_RATE_LIMIT	int
grpc-port	PERMIFY_GRPC_PORT	string
grpc-tls-enabled	PERMIFY_GRPC_TLS_ENABLED	boolean
grpc-tls-key-path	PERMIFY_GRPC_TLS_KEY_PATH	string
grpc-tls-cert-path	PERMIFY_GRPC_TLS_CERT_PATH	string
http-enabled	PERMIFY_HTTP_ENABLED	boolean
http-port	PERMIFY_HTTP_PORT	string
http-grpc-target-host	PERMIFY_HTTP_GRPC_TARGET_HOST	string
http-tls-key-path	PERMIFY_HTTP_TLS_KEY_PATH	string
http-tls-cert-path	PERMIFY_HTTP_TLS_CERT_PATH	string
http-cors-allowed-origins	PERMIFY_HTTP_CORS_ALLOWED_ORIGINS	string array
http-cors-allowed-headers	PERMIFY_HTTP_CORS_ALLOWED_HEADERS	string array

Definition

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

Structure

├── logger
    ├── level

Glossary

Required	Argument	Default	Description
[x]	level	info	logger levels: `error`, `warn`, `info` , `debug`
[x]	output	text	logger output: `json`, `text`

ENV

Argument	ENV	Type
log-level	PERMIFY_LOG_LEVEL	string
log-output	PERMIFY_LOG_OUTPUT	string

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

├── authn
|   ├── method
|   ├── enabled
|   ├── preshared
|       ├── keys

Glossary

Required	Argument	Default	Description
[x]	method	-	Authentication method can be either `oidc` or `preshared`.
[ ]	enabled	true	switch option authentication config
[x]	keys	-	Private key/keys for server authentication. Permify does not provide this key, so it must be generated by the users.

ENV

Argument	ENV	Type
authn-enabled	PERMIFY_AUTHN_ENABLED	boolean
authn-method	PERMIFY_AUTHN_METHOD	string
authn-preshared-keys	PERMIFY_AUTHN_PRESHARED_KEYS	string array

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

├── authn
|   ├── method
|   ├── enabled
|   ├── oidc
|       ├── issuer
|       ├── audience
|       ├── refresh_interval
|       ├── backoff_interval
|       ├── backoff_frequency
|       ├── backoff_max_retries
|       ├── valid_methods

Glossary

Required	Argument	Default	Description
[x]	method	-	Authentication method can be either `oidc` or `preshared`.
[ ]	enabled	false	Switch option to enable or disable authentication config.
[x]	audience	-	The audience identifies the intended recipients of the token, typically the API or resource server. It ensures tokens are used only by the authorized party.
[x]	issuer	-	This is the URL of the provider that is responsible for authenticating users. You will use this URL to discover information about the provider in step 1 of the authentication process.
[x]	refresh_interval	15m	The interval at which the authentication information should be refreshed to ensure that it remains valid and up-to-date.
[x]	backoff_interval	12s	The delay between retries when attempting to authenticate if the key is not found. The system will retry at intervals, which may vary, to avoid constant retry attempts.
[x]	backoff_frequency	-	The duration to wait before retrying after a failed authentication attempt. This helps to manage the load on the authentication service by introducing a delay between retries, ensuring that repeated failures do not overwhelm the service or lead to excessive requests. This value should be configured according to the expected response times and reliability of the authentication provider.
[x]	backoff_max_retries	5	The maximum number of retry attempts to make if key is not found.
[x]	valid_methods	["RS256","HS256"]	A list of accepted signing methods for tokens. This ensures that only tokens signed using one of the specified algorithms will be considered valid.

ENV

Argument	ENV	Type
authn-enabled	PERMIFY_AUTHN_ENABLED	boolean
authn-method	PERMIFY_AUTHN_METHOD	string
authn-oidc-issuer	PERMIFY_AUTHN_OIDC_ISSUER	string
authn-oidc-audience	PERMIFY_AUTHN_OIDC_AUDIENCE	string
authn-oidc-refresh-interval	PERMIFY_AUTHN_OIDC_REFRESH_INTERVAL	duration
authn-oidc-backoff-interval	PERMIFY_AUTHN_OIDC_BACKOFF_INTERVAL	duration
authn-oidc-backoff-frequency	PERMIFY_AUTHN_OIDC_BACKOFF_FREQUENCY	duration
authn-oidc-backoff-max-retries	PERMIFY_AUTHN_OIDC_BACKOFF_RETRIES	int
authn-oidc-valid-methods	PERMIFY_AUTHN_OIDC_VALID_METHODS	string array

Definition

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

Structure

├── tracer
|   ├── exporter
|   ├── endpoint
|   ├── enabled
|   ├── insecure
|   ├── urlpath

Glossary

Required	Argument	Default	Description
[x]	exporter	-	Tracer exporter, the options are `jaeger`, `otlp`, `signoz`, and `zipkin`.
[x]	endpoint	-	export uri for tracing data.
[ ]	enabled	false	switch option for tracing.
[ ]	urlpath		allows one to override the default URL path for otlp, used for sending traces. If unset, default ("/v1/traces") will be used.
[ ]	insecure	false	Whether to use HTTP instead of HTTPs for exporting the traces.

ENV

Argument	ENV	Type
tracer-enabled	PERMIFY_TRACER_ENABLED	boolean
tracer-exporter	PERMIFY_TRACER_EXPORTER	string
tracer-endpoint	PERMIFY_TRACER_ENDPOINT	string
tracer-urlpath	PERMIFY_TRACER_URL_PATH	string
tracer-insecure	PERMIFY_TRACER_INSECURE	boolean

Definition

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

Structure

├── meter
|   ├── exporter
|   ├── endpoint
|   ├── enabled
|   ├── insecure
|   ├── urlpath

Glossary

Required	Argument	Default	Description
[x]	exporter	-	otlp is default.
[x]	endpoint	-	export uri for metric observation
[ ]	enabled	true	switch option for meter tracing.

ENV

Argument	ENV	Type
meter-enabled	PERMIFY_METER_ENABLED	boolean
meter-exporter	PERMIFY_METER_EXPORTER	string
meter-endpoint	PERMIFY_METER_ENDPOINT	string
meter-urlpath	PERMIFY_METER_URL_PATH	string
meter-insecure	PERMIFY_METER_INSECURE	boolean

Definition

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

Structure

├── database
|   ├── engine
|   ├── uri
|   ├── writer.uri
|   ├── reader.uri
|   ├── auto_migrate
|   ├── max_connections
|   ├── max_open_connections (deprecated)
|   ├── max_idle_connections (deprecated)
|   ├── min_connections
|   ├── min_idle_connections
|   ├── max_connection_lifetime
|   ├── max_connection_idle_time
|   ├── health_check_period
|   ├── max_connection_lifetime_jitter
|   ├── connect_timeout
|   ├── max_data_per_write
|   ├── max_retries
|   ├── watch_buffer_size
|   ├──garbage_collection
|       ├──enable: true
|       ├──interval: 3m
|       ├──timeout: 3m
|       ├──window: 720h

Glossary

Required	Argument	Default	Description
[x]	engine	memory	Data source. Permify supports PostgreSQL(`'postgres'`) for now. Contact with us for your preferred database.
[x]	uri	-	Uri of your data source.
[ ]	writer.uri	-	Writer uri of your data source. If not set, uses uri.
[ ]	reader.uri	-	Reader uri of your data source. If not set, uses uri.
[ ]	auto_migrate	true	When its configured as false migrating flow won't work.
[ ]	max_connections	0	Maximum number of connections in the pool (maps to pgxpool MaxConns). 0 means unlimited (pgx default). If not set, max_open_connections will be used for backward compatibility.
[ ]	max_open_connections (deprecated)	20	Deprecated: use max_connections instead. Kept for backward compatibility.
[ ]	max_idle_connections (deprecated)	1	Deprecated: use min_connections instead. Kept for backward compatibility (maps to MinConnections if min_connections is not set).
[ ]	min_connections	0	Minimum number of connections in the pool (maps to pgxpool MinConns). If 0 and max_idle_connections is set, max_idle_connections will be used.
[ ]	min_idle_connections	0	Minimum number of idle connections in the pool (maps to pgxpool MinIdleConns). Must be explicitly set if needed (not set in old code).
[ ]	max_connection_lifetime	300s	Determines the maximum lifetime of a connection in seconds.
[ ]	max_connection_idle_time	60s	Determines the maximum time in seconds that a connection can remain idle before it is closed.
[ ]	health_check_period	0s	Period between health checks on idle connections. 0 means use pgxpool default (1 minute).
[ ]	max_connection_lifetime_jitter	0s	Jitter added to MaxConnLifetime to prevent all connections from expiring at once. 0 means default to 20% of max_connection_lifetime.
[ ]	connect_timeout	0s	Maximum time to wait when establishing a new connection. 0 means use pgx default (no timeout).
[ ]	max_data_per_write	1000	Sets the maximum amount of data per write operation to the database.
[ ]	max_retries	10	Defines the maximum number of retries for database operations in case of failure.
[ ]	watch_buffer_size	100	Specifies the buffer size for database watch operations, impacting how many changes can be queued.
[ ]	enable (for garbage collection)	false	Switch option for garbage collection.
[ ]	interval	3m	Determines the run period of a Garbage Collection operation.
[ ]	timeout	3m	Sets the duration of the Garbage Collection timeout.
[ ]	window	720h	Determines how much backward cleaning the Garbage Collection process will perform.

ENV

Argument	ENV	Type
database-engine	PERMIFY_DATABASE_ENGINE	string
database-uri	PERMIFY_DATABASE_URI	string
database-writer-uri	PERMIFY_DATABASE_WRITER_URI	string
database-reader-uri	PERMIFY_DATABASE_READER_URI	string
database-auto-migrate	PERMIFY_DATABASE_AUTO_MIGRATE	boolean
database-max-connections	PERMIFY_DATABASE_MAX_CONNECTIONS	int
database-max-open-connections (deprecated)	PERMIFY_DATABASE_MAX_OPEN_CONNECTIONS	int
database-max-idle-connections (deprecated)	PERMIFY_DATABASE_MAX_IDLE_CONNECTIONS	int
database-min-connections	PERMIFY_DATABASE_MIN_CONNECTIONS	int
database-min-idle-connections	PERMIFY_DATABASE_MIN_IDLE_CONNECTIONS	int
database-max-connection-lifetime	PERMIFY_DATABASE_MAX_CONNECTION_LIFETIME	duration
database-max-connection-idle-time	PERMIFY_DATABASE_MAX_CONNECTION_IDLE_TIME	duration
database-health-check-period	PERMIFY_DATABASE_HEALTH_CHECK_PERIOD	duration
database-max-connection-lifetime-jitter	PERMIFY_DATABASE_MAX_CONNECTION_LIFETIME_JITTER	duration
database-connect-timeout	PERMIFY_DATABASE_CONNECT_TIMEOUT	duration
database-max-data-per-write	PERMIFY_DATABASE_MAX_DATA_PER_WRITE	int
database-max-retries	PERMIFY_DATABASE_MAX_RETRIES	int
database-watch-buffer-size	PERMIFY_DATABASE_WATCH_BUFFER_SIZE	int
database-garbage-collection-enabled	PERMIFY_DATABASE_GARBAGE_COLLECTION_ENABLED	boolean
database-garbage-collection-interval	PERMIFY_DATABASE_GARBAGE_COLLECTION_INTERVAL	duration
database-garbage-collection-timeout	PERMIFY_DATABASE_GARBAGE_COLLECTION_TIMEOUT	duration
database-garbage-collection-window	PERMIFY_DATABASE_GARBAGE_COLLECTION_WINDOW	duration

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 Example

When using pgcat with session mode, configure Permify to connect through pgcat instead of directly to PostgreSQL:

database:
  engine: postgres
  writer:
    uri: postgresql://postgres:password@pgcat:6432/permify?plan_cache_mode=force_custom_plan&default_query_exec_mode=cache_describe
  reader:
    uri: postgresql://postgres:password@pgcat:6432/permify?plan_cache_mode=force_custom_plan&default_query_exec_mode=cache_describe
  max_connections: 1  # Keep low since pgcat handles pooling
  min_connections: 0
  min_idle_connections: 0
  max_connection_lifetime: 300s
  max_connection_idle_time: 60s

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

├── service
|   ├── circuit_breaker
|   ├── watch:
|   |   ├── enabled
|   ├── schema:
|   |   ├── cache:
|   |   |   ├── number_of_counters
|   |   |   ├── max_cost
|   |   permission:
|   |   |   ├── bulk_limit
|   |   |   ├── concurrency_limit
|   |   |   ├── cache:
|   |   |   |   ├── number_of_counters
|   |   |   |   ├── max_cost

Glossary

Required	Argument	Default	Description
[ ]	circuit_breaker	false	switch option to use the circuit breaker pattern.
[ ]	watch	false	switch option for configuration watcher.
[ ]	schema.cache.number_of_counters	1_000	number of counters for schema service.
[ ]	schema.cache.max_cost	10MiB	max cost for schema cache.
[ ]	permission.bulk_limit	100	bulk operations limit for permission service.
[ ]	permission.concurrency_limit	100	concurrency limit for permission service.
[ ]	permission.cache.max_cost	10MiB	max cost for permission service.

ENV

Argument	ENV	Type
service-circuit-breaker	PERMIFY_SERVICE_CIRCUIT_BREAKER	boolean
service-watch-enabled	PERMIFY_SERVICE_WATCH_ENABLED	boolean
service-schema-cache-number-of-counters	PERMIFY_SERVICE_SCHEMA_CACHE_NUMBER_OF_COUNTERS	int
service-schema-cache-max-cost	PERMIFY_SERVICE_SCHEMA_CACHE_MAX_COST	int
service-permission-bulk-limit	PERMIFY_SERVICE_PERMISSION_BULK_LIMIT	int
service-permission-concurrency-limit	PERMIFY_SERVICE_PERMISSION_CONCURRENCY_LIMIT	int
service-permission-cache-max-cost	PERMIFY_SERVICE_PERMISSION_CACHE_MAX_COST	int

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 execution

When enabled, Permify exposes Go's standard pprof HTTP endpoints on the configured port (default 6060):

Endpoint	Purpose
`GET /debug/pprof/profile?seconds=30`	CPU profile — shows which functions are consuming CPU cycles over the sampling window
`GET /debug/pprof/trace?seconds=5`	Execution trace — records goroutine scheduling, GC, and syscall events
`GET /debug/pprof/heap`	Heap allocation snapshot — identifies memory-heavy code paths
`GET /debug/pprof/goroutine`	List all goroutines and their stack traces — useful for detecting goroutine leaks
`GET /debug/pprof/`	Index of all available profiles

You can analyse captured profiles locally using Go's built-in tooling:

# Download and open a 30-second CPU profile in the interactive UI
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

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

├── profiler
|   ├── enabled
|   ├── port

Glossary

Required	Argument	Default	Description
[ ]	enabled	true	switch option for profiler.
[x]	port	-	port that profiler runs on (default: 6060).

ENV

Argument	ENV	Type
profiler-enabled	PERMIFY_PROFILER_ENABLED	boolean
profiler-port	PERMIFY_PROFILER_PORT	string

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

├── distributed
|   ├── enabled
|   ├── address
|   ├── port

Glossary

Required	Argument	Default	Description
[x]	enabled	false	switch option for distributed.
[]	address	-	address of the distributed service
[]	port	5000	port on which the service is exposed

ENV

Argument	ENV	Type
distributed-enabled	PERMIFY_DISTRIBUTED_ENABLED	boolean
distributed-address	PERMIFY_DISTRIBUTED_ADDRESS	string
distributed-port	PERMIFY_DISTRIBUTED_PORT	string

FilesExpand file tree

configuration.mdx

Latest commit

History

configuration.mdx

File metadata and controls

Configure Using Flags

Configuration Using YAML File

Configuration Glossary

Definition

Structure

Glossary

ENV

Definition

Structure

Glossary

ENV

Definition

Pre Shared Keys

Structure

Glossary

ENV

OpenID Connect

Structure

Glossary

ENV

Definition

Structure

Glossary

ENV

Definition

Structure

Glossary

ENV

Definition

Structure

Glossary

ENV

Production Best Practices: Connection Pooling with pgcat

Definition

Structure

Glossary

ENV

Definition

Structure

Glossary

ENV

Definition

Structure

Glossary

ENV