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,
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:
  rate_limit: 100
  http:
    enabled: true
    port: 3476
    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_open_connections: 20
  max_idle_connections: 1
  max_connection_lifetime: 300s
  max_connection_idle_time: 60s
  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
    ├── rate_limit
    ├── (`grpc` or `http`)
    │   ├── enabled
    │   ├── port
    │   └── tls
    │       ├── enabled
    │       ├── cert
    │       └── key

Glossary

RequiredArgumentDefaultDescription
[ ]rate_limit100the 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)trueswitch option for server.
[x]port-port that server run on.
[x]tls-transport layer security options.
[ ]enabled (for tls)falseswitch option for tls
[ ]cert-tls certificate path.
[ ]key-tls key path

ENV

ArgumentENVType
rate_limitPERMIFY_RATE_LIMITint
grpc-portPERMIFY_GRPC_PORTstring
grpc-tls-enabledPERMIFY_GRPC_TLS_ENABLEDboolean
grpc-tls-key-pathPERMIFY_GRPC_TLS_KEY_PATHstring
grpc-tls-cert-pathPERMIFY_GRPC_TLS_CERT_PATHstring
http-enabledPERMIFY_HTTP_ENABLEDboolean
http-portPERMIFY_HTTP_PORTstring
http-tls-key-pathPERMIFY_HTTP_TLS_KEY_PATHstring
http-tls-cert-pathPERMIFY_HTTP_TLS_CERT_PATHstring
http-cors-allowed-originsPERMIFY_HTTP_CORS_ALLOWED_ORIGINSstring array
http-cors-allowed-headersPERMIFY_HTTP_CORS_ALLOWED_HEADERSstring array

Definition

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

Structure

├── logger
    ├── level

Glossary

RequiredArgumentDefaultDescription
[x]levelinfologger levels: error, warn, info , debug
[x]outputtextlogger output: json, text

ENV

ArgumentENVType
log-levelPERMIFY_LOG_LEVELstring
log-outputPERMIFY_LOG_OUTPUTstring

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

RequiredArgumentDefaultDescription
[x]method-Authentication method can be either oidc or preshared.
[ ]enabledtrueswitch 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

ArgumentENVType
authn-enabledPERMIFY_AUTHN_ENABLEDboolean
authn-methodPERMIFY_AUTHN_METHODstring
authn-preshared-keysPERMIFY_AUTHN_PRESHARED_KEYSstring 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

RequiredArgumentDefaultDescription
[x]method-Authentication method can be either oidc or preshared.
[ ]enabledfalseSwitch 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_interval15mThe interval at which the authentication information should be refreshed to ensure that it remains valid and up-to-date.
[x]backoff_interval12sThe 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_retries5The 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

ArgumentENVType
authn-enabledPERMIFY_AUTHN_ENABLEDboolean
authn-methodPERMIFY_AUTHN_METHODstring
authn-oidc-issuerPERMIFY_AUTHN_OIDC_ISSUERstring
authn-oidc-audiencePERMIFY_AUTHN_OIDC_AUDIENCEstring
authn-oidc-refresh-intervalPERMIFY_AUTHN_OIDC_REFRESH_INTERVALduration
authn-oidc-backoff-intervalPERMIFY_AUTHN_OIDC_BACKOFF_INTERVALduration
authn-oidc-backoff-frequencyPERMIFY_AUTHN_OIDC_BACKOFF_FREQUENCYduration
authn-oidc-backoff-max-retriesPERMIFY_AUTHN_OIDC_BACKOFF_RETRIESint
authn-oidc-valid-methodsPERMIFY_AUTHN_OIDC_VALID_METHODSstring 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

RequiredArgumentDefaultDescription
[x]exporter-Tracer exporter, the options are jaeger, otlp, signoz, and zipkin.
[x]endpoint-export uri for tracing data.
[ ]enabledfalseswitch option for tracing.
[ ]urlpathallows one to override the default URL path for otlp, used for sending traces. If unset, default (“/v1/traces”) will be used.
[ ]insecurefalseWhether to use HTTP instead of HTTPs for exporting the traces.

ENV

ArgumentENVType
tracer-enabledPERMIFY_TRACER_ENABLEDboolean
tracer-exporterPERMIFY_TRACER_EXPORTERstring
tracer-endpointPERMIFY_TRACER_ENDPOINTstring
tracer-urlpathPERMIFY_TRACER_URL_PATHstring
tracer-insecurePERMIFY_TRACER_INSECUREboolean

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

RequiredArgumentDefaultDescription
[x]exporter-otlp is default.
[x]endpoint-export uri for metric observation
[ ]enabledtrueswitch option for meter tracing.

ENV

ArgumentENVType
meter-enabledPERMIFY_METER_ENABLEDboolean
meter-exporterPERMIFY_METER_EXPORTERstring
meter-endpointPERMIFY_METER_ENDPOINTstring
meter-urlpathPERMIFY_METER_URL_PATHstring
meter-insecurePERMIFY_METER_INSECUREboolean

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
|   ├── auto_migrate
|   ├── max_open_connections
|   ├── max_idle_connections
|   ├── max_connection_lifetime
|   ├── max_connection_idle_time
|   ├──garbage_collection
|       ├──enable: true
|       ├──interval: 3m
|       ├──timeout: 3m
|       ├──window: 720h

Glossary

RequiredArgumentDefaultDescription
[x]enginememoryData source. Permify supports PostgreSQL('postgres') for now. Contact with us for your preferred database.
[x]uri-Uri of your data source.
[ ]auto_migratetrueWhen its configured as false migrating flow won’t work.
[ ]max_open_connections20Configuration parameter determines the maximum number of concurrent connections to the database that are allowed.
[ ]max_idle_connections1Determines the maximum number of idle connections that can be held in the connection pool.
[ ]max_connection_lifetime300sDetermines the maximum lifetime of a connection in seconds.
[ ]max_connection_idle_time60sDetermines the maximum time in seconds that a connection can remain idle before it is closed.
[ ]enable (for garbage collection)falseSwitch option for garbage collection.
[ ]interval3mDetermines the run period of a Garbage Collection operation.
[ ]timeout3mSets the duration of the Garbage Collection timeout.
[ ]window720hDetermines how much backward cleaning the Garbage Collection process will perform.

ENV

ArgumentENVType
database-enginePERMIFY_DATABASE_ENGINEstring
database-uriPERMIFY_DATABASE_URIstring
database-auto-migratePERMIFY_DATABASE_AUTO_MIGRATEboolean
database-max-open-connectionsPERMIFY_DATABASE_MAX_OPEN_CONNECTIONSint
database-max-idle-connectionsPERMIFY_DATABASE_MAX_IDLE_CONNECTIONSint
database-max-connection-lifetimePERMIFY_DATABASE_MAX_CONNECTION_LIFETIMEduration
database-max-connection-idle-timePERMIFY_DATABASE_MAX_CONNECTION_IDLE_TIMEduration
database-garbage-collection-enabledPERMIFY_DATABASE_GARBAGE_COLLECTION_ENABLEDboolean
database-garbage-collection-intervalPERMIFY_DATABASE_GARBAGE_COLLECTION_INTERVALduration
database-garbage-collection-timeoutPERMIFY_DATABASE_GARBAGE_COLLECTION_TIMEOUTduration
database-garbage-collection-windowPERMIFY_DATABASE_GARBAGE_COLLECTION_WINDOWduration

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

RequiredArgumentDefaultDescription
[ ]circuit_breakerfalseswitch option to use the circuit breaker pattern.
[ ]watchfalseswitch option for configuration watcher.
[ ]schema.cache.number_of_counters1_000number of counters for schema service.
[ ]schema.cache.max_cost10MiBmax cost for schema cache.
[ ]permission.bulk_limit100bulk operations limit for permission service.
[ ]permission.concurrency_limit100concurrency limit for permission service.
[ ]permission.cache.max_cost10MiBmax cost for permission service.

ENV

ArgumentENVType
service-circuit-breakerPERMIFY_SERVICE_CIRCUIT_BREAKERboolean
service-watch-enabledPERMIFY_SERVICE_WATCH_ENABLEDboolean
service-schema-cache-number-of-countersPERMIFY_SERVICE_SCHEMA_CACHE_NUMBER_OF_COUNTERSint
service-schema-cache-max-costPERMIFY_SERVICE_SCHEMA_CACHE_MAX_COSTint
service-permission-bulk-limitPERMIFY_SERVICE_PERMISSION_BULK_LIMITint
service-permission-concurrency-limitPERMIFY_SERVICE_PERMISSION_CONCURRENCY_LIMITint
service-permission-cache-max-costPERMIFY_SERVICE_PERMISSION_CACHE_MAX_COSTint

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

Structure

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

Glossary

RequiredArgumentDefaultDescription
[ ]enabledtrueswitch option for profiler.
[x]port-port that profiler runs on (default: 6060).

ENV

ArgumentENVType
profiler-enabledPERMIFY_PROFILER_ENABLEDboolean
profiler-portPERMIFY_PROFILER_PORTstring

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

RequiredArgumentDefaultDescription
[x]enabledfalseswitch option for distributed.
[]address-address of the distributed service
[]port5000port on which the service is exposed

ENV

ArgumentENVType
distributed-enabledPERMIFY_DISTRIBUTED_ENABLEDboolean
distributed-addressPERMIFY_DISTRIBUTED_ADDRESSstring
distributed-portPERMIFY_DISTRIBUTED_PORTstring
I