### Development Configuration Setup

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/4-configuration.md

Example YAML configuration for a local development environment with anonymous authentication enabled.

```yaml
version: 2

logging:
  log_level: debug
  prod: false

directory:
  db_path: ~/.local/share/topaz/db/topaz.db

remote_directory:
  url: localhost:9292
  insecure: true

api:
  services:
    authorizer:
      grpc:
        listen_address: :8282
      gateway:
        listen_address: :8383
      needs:
        - reader

    reader:
      grpc:
        listen_address: :9292
      gateway:
        listen_address: :9393

    console:
      grpc:
        listen_address: :8282
      gateway:
        listen_address: :8080

opa:
  log_level: debug
  local_bundles:
    paths:
      - ~/.config/topaz/policies
    watch: true

auth:
  anonymous: true  # Development only
```

--------------------------------

### Production Configuration Setup

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/4-configuration.md

Example YAML configuration for production, including TLS certificate paths and remote OPA bundle services.

```yaml
version: 2

logging:
  log_level: info
  prod: true

directory:
  db_path: /var/lib/topaz/directory.db
  request_timeout: 30s

remote_directory:
  url: directory-svc.prod.local:9292
  insecure: false

api:
  health:
    listen_address: :9494
  metrics:
    listen_address: :9696
  services:
    authorizer:
      grpc:
        listen_address: :8282
        certs:
          cert_file: /etc/topaz/certs/grpc.crt
          key_file: /etc/topaz/certs/grpc.key
      gateway:
        listen_address: :8383
        certs:
          cert_file: /etc/topaz/certs/gateway.crt
          key_file: /etc/topaz/certs/gateway.key
      needs:
        - reader

    reader:
      grpc:
        listen_address: :9292
        certs:
          cert_file: /etc/topaz/certs/grpc.crt
          key_file: /etc/topaz/certs/grpc.key
      gateway:
        listen_address: :9393
        certs:
          cert_file: /etc/topaz/certs/gateway.crt
          key_file: /etc/topaz/certs/gateway.key

opa:
  log_level: error
  config:
    services:
      default:
        url: https://opa-bundle-server.example.com
    bundles:
      topaz:
        service: default
        resource: bundles/topaz

jwt:
  acceptable_time_skew_seconds: 5

auth:
  api_key: ${TOPAZ_API_KEY}  # From environment or secrets manager
  api_key_header: Authorization
```

--------------------------------

### Install Todo Template

Source: https://github.com/aserto-dev/topaz/blob/main/README.md

Installs the pre-built Todo template including policy, domain model, and sample data.

```console
$ topaz templates install todo
```

--------------------------------

### Install Topaz via Go

Source: https://github.com/aserto-dev/topaz/blob/main/README.md

Use the Go toolchain to install the latest version of Topaz.

```console
$ go install github.com/aserto-dev/topaz/topaz@latest
```

--------------------------------

### Start Topaz Servers

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Initiates the server manager to start health, metrics, gRPC, and gateway servers.

```go
err := e.Manager.StartServers(e.Context)
if err != nil {
    return err
}
```

--------------------------------

### Install Topaz via Homebrew

Source: https://github.com/aserto-dev/topaz/blob/main/README.md

Use this command to install the Topaz binary on macOS or Linux using Homebrew.

```console
$ brew install --cask aserto-dev/tap/topaz
```

--------------------------------

### Manage Dependencies

Source: https://github.com/aserto-dev/topaz/blob/main/CLAUDE.md

Commands to install development tools and maintain go.mod files.

```bash
# Install all development dependencies (vault, svu, goreleaser, golangci-lint, gotestsum, wire, etc.)
make deps

# Tidy go.mod files
make go-mod-tidy
```

--------------------------------

### Troubleshoot Service Startup

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Verify configuration, port availability, and file permissions when the service fails to start.

```bash
# Check configuration
topazd run --config-file config.yaml 2>&1

# Check port availability
netstat -tln | grep 8282

# Check file permissions
ls -la ~/.local/share/topaz/
```

--------------------------------

### Setup Directory and Runtime Resolvers

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Configures the directory resolver and OPA runtime, then injects them into the authorizer service.

```go
if _, ok := topazApp.Services["authorizer"]; ok {
    dirResolver, err := directory.NewResolver(
        topazApp.Logger,
        &topazApp.Configuration.DirectoryResolver,
    )
    
    runtime, runtimeCleanup, err := topaz.NewRuntimeResolver(
        topazApp.Context,
        topazApp.Logger,
        topazApp.Configuration,
        dirResolver.GetConn(),
    )
    
    if authorizer, ok := topazApp.Services["authorizer"].(*app.Authorizer); ok {
        authorizer.Resolver.SetRuntimeResolver(runtime)
        authorizer.Resolver.SetDirectoryResolver(dirResolver)
    }
}
```

--------------------------------

### Retrieve Authorizer Info

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Signature and usage example for fetching version and build metadata from the authorizer.

```go
func (s *AuthorizerServer) Info(ctx context.Context, req *authorizer.InfoRequest) (*authorizer.InfoResponse, error)
```

```go
resp, err := authorizerServer.Info(ctx, &authorizer.InfoRequest{})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Topaz %s (%s) built on %s\n", resp.Version, resp.Commit, resp.Date)
```

--------------------------------

### Install Topaz Authorizer

Source: https://github.com/aserto-dev/topaz/blob/main/README.md

Downloads the latest Topaz authorizer Docker container image.

```console
$ topaz install
```

--------------------------------

### Readiness Probe Response

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Example JSON response indicating the service is ready.

```json
{
  "status": "SERVING"
}
```

--------------------------------

### Define a directory.Object

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/5-types-reference.md

Example of an Object entity representing a user within the directory.

```protobuf
Object {
  type: "user"
  id: "user@example.com"
  display_name: "Alice"
  properties: {
    "email": "user@example.com"
    "department": "engineering"
    "active": true
  }
}
```

--------------------------------

### Configure the editor

Source: https://github.com/aserto-dev/topaz/blob/main/docs/fflag/topaz-edit-mode.md

Examples of setting the editor environment variable for Topaz.

```bash
export TOPAZ_EDITOR=nvim
export TOPAZ_EDITOR='code --watch'
export TOPAZ_EDITOR=micro
```

--------------------------------

### ListPolicies Usage

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Example of listing policies and iterating through the results to print metadata.

```go
resp, err := authorizerServer.ListPolicies(ctx, &authorizer.ListPoliciesRequest{})
if err != nil {
    return err
}
for _, policy := range resp.Result {
    fmt.Printf("Policy %s in package %s\n", policy.GetId(), policy.GetPackagePath())
}
```

--------------------------------

### Authorizer Service Request

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/INDEX.md

Example of making an authorization request using the Go SDK.

```go
resp, err := authorizerServer.Is(ctx, &authorizer.IsRequest{
    // ...
})
```

--------------------------------

### Verify feature flag activation

Source: https://github.com/aserto-dev/topaz/blob/main/docs/fflag/topaz-fflag.md

Example output showing the edit request flag enabled in the help menu.

```text
 -e, --edit                     edit request
```

--------------------------------

### GetPolicy Usage

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Example of retrieving a specific policy by ID and accessing its raw source code.

```go
resp, err := authorizerServer.GetPolicy(ctx, &authorizer.GetPolicyRequest{
    Id: "todoApp",
})
if err != nil {
    return err
}
fmt.Printf("Raw policy:\n%s\n", resp.Result.GetRaw())
```

--------------------------------

### HTTP Load Balancer Configuration

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Example Nginx configuration for load balancing HTTP traffic.

```nginx
upstream topaz_http {
    least_conn;
    server 10.0.1.1:8383;
    server 10.0.1.2:8383;
    server 10.0.1.3:8383;
}

server {
    listen 8383;
    location / {
        proxy_pass http://topaz_http;
        proxy_http_version 1.1;
        proxy_buffering off;
    }
}
```

--------------------------------

### Example JSON response

Source: https://github.com/aserto-dev/topaz/blob/main/docs/fflag/topaz-edit-mode.md

The output format returned after a successful edit mode operation.

```json
{
  "check":  true,
  "trace":  []
}
```

--------------------------------

### View Topaz Configuration Artifacts

Source: https://github.com/aserto-dev/topaz/blob/main/README.md

Displays the directory structure of installed Topaz configuration and template files.

```console
$ tree $HOME/.config/topaz
/Users/ogazitt/.config/topaz
├── cfg
│   └── todo.yaml
├── todo
│   ├── data
│   │   ├── citadel_objects.json
│   │   ├── citadel_relations.json
│   │   ├── todo_objects.json
│   │   └── todo_relations.json
│   └── model
│       └── manifest.yaml
└── topaz.json
```

--------------------------------

### Anonymous Access Policy Example

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/7-authentication-and-authorization.md

Rego policy demonstrating how to handle null user input when anonymous access is enabled.

```rego
package todoApp.allowed

default allowed = false

allowed if {
    # Allow access if no user (anonymous)
    input.user == null
} else {
    # Or allow if user is authenticated and active
    input.user != null
    input.user.properties.active == true
}
```

--------------------------------

### Configure API Services

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/4-configuration.md

Example YAML configuration for defining gRPC and HTTP gateway settings for the authorizer service, including dependency management.

```yaml
services:
  authorizer:
    grpc:
      listen_address: :8282
      certs:
        cert_file: path/to/cert
        key_file: path/to/key
    gateway:
      listen_address: :8383
      certs:
        cert_file: path/to/cert
        key_file: path/to/key
    needs:
      - reader     # Authorizer depends on reader for identity resolution
```

--------------------------------

### Run Topaz in a Docker Container

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Starts a Topaz container with necessary port mappings and volume mounts for configuration and data persistence.

```bash
docker run -d \
  --name topaz \
  -p 8282:8282 \
  -p 8383:8383 \
  -p 8080:8080 \
  -p 9292:9292 \
  -p 9393:9393 \
  -p 9494:9494 \
  -p 9696:9696 \
  -v ~/.config/topaz:/root/.config/topaz \
  -v ~/.local/share/topaz:/root/.local/share/topaz \
  ghcr.io/aserto-dev/topaz:latest \
  run --config-file /root/.config/topaz/cfg/topaz.yaml
```

--------------------------------

### Incorrect OPA Decision Logs Configuration

Source: https://github.com/aserto-dev/topaz/blob/main/topazd/authorizer/plugins/topaz_file_decision_logger/topaz_file_decision_logger.md

An example of an incorrect configuration attempt that should be avoided.

```yaml
    decision_logs:
      console: false
      plugin: topaz_file_decision_logger # !!! DO NOT ADD THIS !!!
```

--------------------------------

### gRPC Load Balancer Configuration

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Example HAProxy configuration for load balancing gRPC traffic.

```text
listen topaz_grpc
    bind *:8282
    mode tcp
    balance roundrobin
    option tcp-check
    tcp-check connect port 8282
    server topaz1 10.0.1.1:8282 check
    server topaz2 10.0.1.2:8282 check
    server topaz3 10.0.1.3:8282 check
```

--------------------------------

### Deploy Topaz on Kubernetes

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Example manifests for deploying Topaz in a Kubernetes cluster, including the Deployment, ConfigMap, PVC, and Service resources.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: topaz
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: topaz
  template:
    metadata:
      labels:
        app: topaz
    spec:
      containers:
      - name: topaz
        image: ghcr.io/aserto-dev/topaz:latest
        imagePullPolicy: IfNotPresent
        args:
          - run
          - --config-file
          - /etc/topaz/config.yaml
        
        ports:
        - name: grpc-auth
          containerPort: 8282
          protocol: TCP
        - name: http-auth
          containerPort: 8383
          protocol: TCP
        - name: grpc-dir
          containerPort: 9292
          protocol: TCP
        - name: http-dir
          containerPort: 9393
          protocol: TCP
        - name: http-console
          containerPort: 8080
          protocol: TCP
        - name: health
          containerPort: 9494
          protocol: TCP
        - name: metrics
          containerPort: 9696
          protocol: TCP
        
        env:
        - name: TOPAZ_LOGGING_LOG_LEVEL
          value: "info"
        - name: TOPAZ_DIRECTORY_DB_PATH
          value: "/data/topaz.db"
        - name: TOPAZ_AUTH_API_KEY
          valueFrom:
            secretKeyRef:
              name: topaz-secrets
              key: api-key
        
        volumeMounts:
        - name: config
          mountPath: /etc/topaz
          readOnly: true
        - name: data
          mountPath: /data
        - name: policies
          mountPath: /policies
          readOnly: true
        
        readinessProbe:
          grpc:
            port: 9494
            service: authorizer
          initialDelaySeconds: 5
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3
        
        livenessProbe:
          grpc:
            port: 9494
            service: authorizer
          initialDelaySeconds: 10
          periodSeconds: 30
          timeoutSeconds: 5
          failureThreshold: 3
        
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "1Gi"
            cpu: "1000m"
      
      volumes:
      - name: config
        configMap:
          name: topaz-config
      - name: data
        persistentVolumeClaim:
          claimName: topaz-data
      - name: policies
        configMap:
          name: topaz-policies

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: topaz-config
data:
  topaz.yaml: |
    version: 2
    logging:
      log_level: info
      prod: true
    directory:
      db_path: /data/topaz.db
    api:
      health:
        listen_address: :9494
      metrics:
        listen_address: :9696
      services:
        authorizer:
          grpc:
            listen_address: :8282
          gateway:
            listen_address: :8383
          needs:
            - reader
        reader:
          grpc:
            listen_address: :9292
          gateway:
            listen_address: :9393

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: topaz-data
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

---
apiVersion: v1
kind: Service
metadata:
  name: topaz
spec:
  type: ClusterIP
  selector:
    app: topaz
  ports:
  - name: grpc-auth
    port: 8282
    targetPort: 8282
  - name: http-auth
    port: 8383
    targetPort: 8383
  - name: grpc-dir
    port: 9292
    targetPort: 9292
  - name: http-dir
    port: 9393
    targetPort: 9393
  - name: console
    port: 8080
    targetPort: 8080
```

--------------------------------

### Execute inline JSON request

Source: https://github.com/aserto-dev/topaz/blob/main/docs/fflag/topaz-edit-mode.md

Example of providing a JSON payload directly via the command line.

```console
$ topaz directory get object '{"object_type":"user", "object_id":"euang@acmecorp.com"}' --insecure
```

--------------------------------

### Topaz Log Output Formats

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Examples of human-readable logs for development and JSON logs for production environments.

```text
16:45:23 INF starting service component=authorizer service=authorizer
16:45:24 DBG policy evaluation latency_ms=12 path=todoApp.allowed
```

```json
{"time":"2024-01-20T16:45:23Z","level":"info","component":"authorizer","msg":"starting service","service":"authorizer"}
{"time":"2024-01-20T16:45:24Z","level":"debug","component":"api.grpc","msg":"policy evaluation","latency_ms":12,"path":"todoApp.allowed"}
```

--------------------------------

### Example Rego Policy Using Identity

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/7-authentication-and-authorization.md

Demonstrates a Rego policy that validates user status and checks resource ownership via the directory service.

```rego
package todoApp.allowed

default allowed = false

allowed if {
    # User must be active
    input.user.properties.active == true
    
    # User must own the resource
    ds.check({
        "subject_type": "user",
        "subject_id": input.user.id,
        "relation": "owner",
        "object_type": input.resource.type,
        "object_id": input.resource.id
    })
}
```

--------------------------------

### Evaluate Authorization Decisions

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Signature and usage example for evaluating authorization decisions against a specific policy, user, and resource.

```go
func (s *AuthorizerServer) Is(ctx context.Context, req *authorizer.IsRequest) (*authorizer.IsResponse, error)
```

```go
resp, err := authorizerServer.Is(ctx, &authorizer.IsRequest{
    IdentityContext: &api.IdentityContext{
        Type:     api.IdentityType_IDENTITY_TYPE_SUB,
        Identity: "user@example.com",
    },
    PolicyContext: &api.PolicyContext{
        Path:      "todoApp.GET.todos",
        Decisions: []string{"allowed"},
    },
    ResourceContext: &structpb.Struct{
        Fields: map[string]*structpb.Value{
            "owner_id": structpb.NewStringValue("user123"),
        },
    },
})
if err != nil {
    return err
}
for _, d := range resp.Decisions {
    fmt.Printf("%s: %v\n", d.Decision, d.Is)
}
```

--------------------------------

### ServiceManager API Methods

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Core methods for managing server lifecycles, including adding, starting, and stopping servers, as well as configuring health and metrics endpoints.

```go
// Add a server
func (m *ServiceManager) AddGRPCServer(server *Server) error

// Start all servers
func (m *ServiceManager) StartServers(ctx context.Context) error

// Stop all servers gracefully
func (m *ServiceManager) StopServers()

// Setup health check server
func (m *ServiceManager) SetupHealthServer(address string, certs *client.TLSConfig) error

// Setup metrics server
func (m *ServiceManager) SetupMetricsServer(address string, certs *client.TLSConfig, debug bool) ([]grpc.ServerOption, error)
```

--------------------------------

### Get OPA Runtime

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Retrieves the current OPA runtime from the runtime resolver. Returns an error if the resolver is not configured.

```go
func (s *AuthorizerServer) getRuntime(ctx context.Context) (*runtime.Runtime, error)
```

--------------------------------

### Build and Run Topaz from Source

Source: https://github.com/aserto-dev/topaz/blob/main/README.md

Compile the project from source and execute the resulting binary.

```console
$ make build && ./dist/build_linux_amd64/topaz
```

--------------------------------

### GET /api/v3/objects

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/2-directory-api.md

Retrieves an object from the directory by type and ID.

```APIDOC
## GET /api/v3/objects

### Description
Retrieves a specific object from the directory.

### Method
GET

### Endpoint
/api/v3/objects

### Parameters
#### Query Parameters
- **object_type** (string) - Required - The type of the object
- **object_id** (string) - Required - The unique identifier of the object
```

--------------------------------

### Build Topaz Application Instance

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Initializes the Topaz application using Google Wire for dependency injection.

```go
topazApp, cleanup, err := topaz.BuildApp(
    os.Stdout,      // stdout
    os.Stderr,      // stderr
    configPath,     // config file path
    configOverrides // override function
)
defer cleanup()  // Cleanup function for dependency injection (Wire)
```

--------------------------------

### Initialize Application Context

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Creates a context with signal handling for graceful shutdown and lifecycle management.

```go
ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
```

--------------------------------

### Initialize API Key Middleware

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/7-authentication-and-authorization.md

Creates a new API key authentication middleware instance using the provided context, configuration, and logger.

```go
apiKeyAuthMiddleware, err := authentication.NewAPIKeyAuthMiddleware(
    ctx,
    &config.Auth,
    logger,
)
```

--------------------------------

### Initialize AuthorizerServer

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Constructor for creating a new AuthorizerServer instance with required dependencies.

```go
func NewAuthorizerServer(
    ctx context.Context,
    logger *zerolog.Logger,
    cfg *config.Common,
    rf *resolvers.Resolvers,
) *AuthorizerServer
```

--------------------------------

### Initialize Logger via Configuration

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Define log level and output format in the configuration file.

```yaml
logging:
  log_level: debug          # off, debug, info, warn, error, fatal
  prod: false               # false = human-readable, true = JSON
```

--------------------------------

### Initialize OPA Runtime

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Initializes the OPA runtime, including bundle loading, custom built-ins, and decision logging.

```go
runtime, runtimeCleanup, err := topaz.NewRuntimeResolver(
    ctx,
    logger,
    config,
    dirResolverConn,  // Directory for built-ins
)
```

--------------------------------

### Verify Readiness via grpcurl

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Uses grpcurl to manually check the readiness status of the authorizer service.

```bash
grpcurl -plaintext localhost:9494 grpc.health.v1.Health/Check -d '{"service":"authorizer"}'
```

--------------------------------

### Build Topaz

Source: https://github.com/aserto-dev/topaz/blob/main/CLAUDE.md

Commands to build the Topaz binary for the current platform and verify the output.

```bash
# Build for current platform (requires Go 1.25+ in environment)
make build

# Build output: dist/build_<os>_<arch>/topaz
./dist/build_linux_amd64/topaz --help
```

--------------------------------

### JWT Subject Claim Example

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/7-authentication-and-authorization.md

Represents the subject claim extracted from a JWT for identity resolution.

```json
{
  "sub": "user@example.com"
}
```

--------------------------------

### Retrieve full Topaz configuration info

Source: https://github.com/aserto-dev/topaz/blob/main/docs/config.md

Outputs the complete configuration state, including environment, runtime, and service settings.

```bash
topaz config info
{
  "environment": {
    "home": "/Users/gertd",
    "xdg_config_home": "/Users/gertd/.config",
    "xdg_data_home": "/Users/gertd/.local/share"
  },
  "config": {
    "topaz_cfg_dir": "/Users/gertd/.config/topaz/cfg",
    "topaz_certs_dir": "/Users/gertd/.local/share/topaz/certs",
    "topaz_db_dir": "/Users/gertd/.local/share/topaz/db",
    "topaz_tmpl_dir": "/Users/gertd/.local/share/topaz/tmpl",
    "topaz_dir": "/Users/gertd/.config/topaz"
  },
  "runtime": {
    "active_configuration_name": "gdrive-v33",
    "active_configuration_file": "/Users/gertd/.config/topaz/cfg/gdrive-v33.yaml",
    "running_configuration_name": "test-dlog",
    "running_configuration_file": "/Users/gertd/.config/topaz/cfg/test-dlog.yaml",
    "running_container_name": "topaz-test-dlog",
    "topaz_json": "/Users/gertd/.config/topaz/topaz.json"
  },
  "default": {
    "container_registry": "ghcr.io/aserto-dev",
    "container_image": "topaz",
    "container_tag": "0.33.14",
    "container_platform": "linux/arm64",
    "topaz_no_check": false,
    "topaz_no_color": false
  },
  "directory": {
    "topaz_directory_svc": "localhost:9292",
    "topaz_directory_key": "",
    "topaz_directory_token": "",
    "topaz_insecure": false
  },
  "authorizer": {
    "topaz_authorizer_svc": "localhost:8282",
    "topaz_authorizer_key": "",
    "topaz_authorizer_token": "",
    "topaz_insecure": false
  }
}
```

--------------------------------

### Health Check CLI Command

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/INDEX.md

Example of using grpcurl to check the health status of the service.

```bash
grpcurl -plaintext localhost:8282 grpc.health.v1.Health/Check
```

--------------------------------

### Initialize Directory Resolver

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Configures the directory resolver client with gRPC dial options and connection settings.

```go
dirResolver, err := directory.NewResolver(
    logger,
    &config.DirectoryResolver,
)
```

--------------------------------

### Access User Properties in Rego

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/7-authentication-and-authorization.md

Example of using the resolved user object within a Rego policy.

```rego
package todoApp.allowed

default allowed = false

allowed if {
    input.user.properties.active == true
    input.user.properties.department == "engineering"
}
```

--------------------------------

### Configure Topaz Services

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Initializes health/metrics, prepares service implementations, and validates configuration.

```go
metricsMiddleware, err := e.setupHealthAndMetrics()
```

```go
if err := e.prepareServices(); err != nil {
    return err
}
```

```go
if err := e.validateConfig(); err != nil {
    return err
}
```

--------------------------------

### DecisionTree Usage

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Example of invoking the DecisionTree method to retrieve decision outcomes for a specific policy path.

```go
resp, err := authorizerServer.DecisionTree(ctx, &authorizer.DecisionTreeRequest{
    PolicyContext: &api.PolicyContext{
        Path:      "todoApp",
        Decisions: []string{"allowed", "admin"},
    },
    IdentityContext: &api.IdentityContext{
        Type:     api.IdentityType_IDENTITY_TYPE_SUB,
        Identity: "user@example.com",
    },
    Options: &authorizer.DecisionTreeOptions{
        PathSeparator: authorizer.PathSeparator_PATH_SEPARATOR_DOT,
    },
})
if err != nil {
    return err
}
// resp.Path contains decision outcomes for all matching rules
paths := resp.Path.AsMap()
```

--------------------------------

### Load Configuration in Topaz

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Loads configuration from a file and environment variables, applying optional overrides.

```go
configPath := config.Path(flagRunConfigFile)

// Load from file + environment variables
configLoader, err := config.LoadConfiguration(configPath)
if err != nil {
    return err
}

// Apply overrides
if overrides != nil {
    overrides(configLoader.Configuration)
}
```

--------------------------------

### List topaz-backup commands

Source: https://github.com/aserto-dev/topaz/blob/main/topaz-backup/README.md

Displays the available commands and flags for the topaz-backup utility.

```bash
topaz-backup
Usage: topaz-backup <command>

topaz backup utility

Commands:
  boltdb    boltdb plugin

Flags:
  -h, --help    Show context-sensitive help.

Run "topaz-backup <command> --help" for more information on a command.

topaz-backup: error: expected "boltdb"
```

--------------------------------

### Configure Tracing and Logging

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Enable verbose logging and OPA policy tracing.

```yaml
logging:
  log_level: debug
```

```bash
topazd run --config config.yaml  # Verbose logging from OPA
```

--------------------------------

### Read Directory Objects

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/2-directory-api.md

Retrieve object details using gRPC request structures or REST GET endpoints.

```proto
// gRPC
GetObjectRequest {
  object_type: "user"
  object_id: "user@example.com"
}
```

```http
// REST
GET /api/v3/objects?object_type=user&object_id=user@example.com
```

--------------------------------

### Decision Tree Response Structure

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/5-types-reference.md

Example JSON structure representing the nested path mapping for decision outcomes.

```json
{
  "GET": {
    "allowed": true,
    "audit": false
  },
  "POST": {
    "allowed": false,
    "audit": false
  }
}
```

--------------------------------

### Run Tests

Source: https://github.com/aserto-dev/topaz/blob/main/CLAUDE.md

Commands for executing the full test suite, specific packages, or unit tests.

```bash
# Run all tests (builds test snapshot, runs integration tests)
make test

# Run specific test suites
make run-tests

# Run only unit tests without building snapshot
./.ext/bin/gotestsum --format short-verbose -- -count=1 -timeout 120s -parallel=1 -v ./pkg/app/tests/...

# Test single package
go test -v ./pkg/app/tests/ds -count=1
```

--------------------------------

### Display Topaz CLI Help

Source: https://github.com/aserto-dev/topaz/blob/main/README.md

View the available commands and flags for the Topaz CLI.

```console
$ topaz --help

Usage: topaz <command> [flags]

Topaz CLI

Commands:
  run                run topaz in console mode
  start              start topaz in daemon mode
  stop               stop topaz instance
  restart            restart topaz instance
  status             status of topaz daemon process
  manifest           manifest commands
  templates          template commands
  console            open console in the browser
  directory (ds)     directory commands
  authorizer (az)    authorizer commands
  config             configure topaz service
  certs              cert commands
  install            install topaz container
  uninstall          uninstall topaz container
  update             update topaz container version
  version            version information

Flags:
  -h, --help        Show context-sensitive help.
  -N, --no-check    disable local container status check ($TOPAZ_NO_CHECK)
  -L, --log         log level

Run "topaz <command> --help" for more information on a command.
```

--------------------------------

### Configure local bundle paths

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/4-configuration.md

Set directories or files for local policy loading, supporting wildcards and home directory expansion.

```yaml
opa:
  local_bundles:
    paths:
      - ~/.config/topaz/policies
      - /opt/policies/*.rego
```

--------------------------------

### Info

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Returns version, build metadata, and runtime information about the authorizer.

```APIDOC
## Info

### Description
Returns version, build metadata, and runtime information about the authorizer.

### Signature
`func (s *AuthorizerServer) Info(ctx context.Context, req *authorizer.InfoRequest) (*authorizer.InfoResponse, error)`

### Parameters
- **ctx** (context.Context) - Required - Request context
- **req** (*authorizer.InfoRequest) - Required - Empty request

### Response
- **Version** (string) - Semantic version of Topaz build
- **Commit** (string) - Git commit hash
- **Date** (string) - Build date
- **Os** (string) - Operating system (GOOS)
- **Arch** (string) - CPU architecture (GOARCH)
```

--------------------------------

### List boltdb plugin arguments

Source: https://github.com/aserto-dev/topaz/blob/main/topaz-backup/README.md

Shows the required flags for the boltdb backup plugin.

```bash
topaz-backup boltdb

Usage: topaz-backup boltdb --db-file=STRING --backup-dir=STRING

boltdb plugin

Flags:
  -h, --help                 Show context-sensitive help.

      --db-file=STRING       database file path
      --backup-dir=STRING    backup directory path

topaz-backup: error: missing flags: --backup-dir=STRING, --db-file=STRING
```

--------------------------------

### Run Topaz with Docker

Source: https://github.com/aserto-dev/topaz/blob/main/README.md

Execute the Topaz container image directly using Docker.

```console
$ docker run -it --rm ghcr.io/aserto-dev/topaz:latest --help
```

--------------------------------

### Authenticate with API Key via cURL

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/7-authentication-and-authorization.md

Demonstrates how to provide the API key using Bearer token format or a custom header.

```bash
# Bearer token format
curl -H "Authorization: Bearer my-secret-key" https://localhost:8383/api/v2/authz/is

# Custom header
curl -H "X-API-Key: my-secret-key" https://localhost:8383/api/v2/authz/is
```

--------------------------------

### Initialize EdgeDir Service

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/2-directory-api.md

Constructor for creating a new EdgeDir instance using an existing directory backend.

```go
func NewEdgeDir(edge *directory.Directory) (*EdgeDir, error)
```

--------------------------------

### Generate a new configuration with Topaz CLI

Source: https://github.com/aserto-dev/topaz/blob/main/docs/config.md

Use this command to create a new configuration file template based on a specific policy.

```bash
topaz config new --name my-topaz --resource ghcr.io/aserto-policies/policy-rebac:latest --policy rebac --stdout
```

--------------------------------

### Configure Topaz OPA and Plugins

Source: https://github.com/aserto-dev/topaz/blob/main/docs/config.md

Full YAML configuration for Topaz, including OPA instance settings, OCI registry bundle sources, and plugin definitions for decision logging and directory synchronization.

```yaml
opa:
  instance_id: "-"
  graceful_shutdown_period_seconds: 2
  # max_plugin_wait_time_seconds: 30 set as default
  local_bundles:
    paths: []
    skip_verification: true
  config:
    services:
      policy-registry:
        url: "https://ghcr.io"
        type: "oci"
        credentials:
          bearer:
            scheme: "Bearer"
            token: "${GIT_TOKEN}"
        response_header_timeout_seconds: 15
    bundles:
      rebac:
        service: policy-registry
        resource: "ghcr.io/aserto-policies/policy-rebac:latest"
        persist: false
        config:
          polling:
            min_delay_seconds: 60
            max_delay_seconds: 120
    decision_logs:
      console: false
    plugins:
      # topaz file decision logger plugin configuration
      topaz_file_decision_logger:
        enabled: false
        logger:
          filename: '${TOPAZ_DECISIONS_DIR}/my-topaz.json'
          max_size: 100
          max_age: 0
          max_backups: 0
          local_time: false
          compress: false
        policy_info:
          policy_name: 'rebac'
          registry_service: 'ghcr.io'
          registry_image: 'aserto-policies/policy-rebac'
          registry_tag: 'latest'
          digest: ''
          
      # aserto edge directory sync plugin configuration
      aserto_edge:
        enabled: false
        addr: ""                    # gRPC directory service address.
        apikey: ""                  # directory API key.
        timeout: 5                  # gRPC connection timeout in seconds.
        sync_interval: 1            # sync run interval in minutes.
        insecure: true              # when using TLS connections, skip verification of the server certificate.
        page_size: 0                # deprecated: no longer used.
        client_cert_path: ""        # when using mTLS connections, ClientCertPath is the path of the client's certificate file.
        client_key_path: ""         # when using mTLS connections, ClientKeyPath is the path of the client's private key file.
        no_tls: false               # disable TLS and use a plaintext connection.
        no_proxy: false             # bypasses any configured HTTP proxy.
        headers:                    # additional headers to include in requests to the service.
```

--------------------------------

### Container Operations

Source: https://github.com/aserto-dev/topaz/blob/main/CLAUDE.md

Commands for building and running local test snapshot containers.

```bash
# Build test snapshot container
make test-snapshot
# Output: ghcr.io/aserto-dev/topaz:0.0.0-test-<git-sha>-<arch>

# Run local test snapshot
make run-test-snapshot
make start-test-snapshot
```

--------------------------------

### Enable and use edit mode

Source: https://github.com/aserto-dev/topaz/blob/main/docs/fflag/topaz-edit-mode.md

Set the feature flag and execute a command using the --edit flag.

```bash
export TOPAZ_FFLAG=1
topaz directory check --edit --insecure
```

--------------------------------

### Build Application Dependencies with Wire

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Defines the signature for building application dependencies in the Topaz service.

```go
// Build application dependencies
func BuildApp(
    stdout io.Writer,
    stderr io.Writer,
    configPath config.Path,
    overrides config.Overrider,
) (*Topaz, func(), error)
```

--------------------------------

### Configure TLS/SSL Certificates

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Define certificate and key file paths in the Topaz configuration file.

```yaml
api:
  services:
    authorizer:
      grpc:
        certs:
          cert_file: ~/.local/share/topaz/certs/grpc.crt
          key_file: ~/.local/share/topaz/certs/grpc.key
```

```yaml
api:
  services:
    authorizer:
      grpc:
        certs:
          cert_file: /etc/topaz/certs/server.crt
          key_file: /etc/topaz/certs/server.key
```

--------------------------------

### Generate Code

Source: https://github.com/aserto-dev/topaz/blob/main/CLAUDE.md

Command to trigger Google Wire dependency injection code generation.

```bash
# Generate wire dependency injection code
make generate

# Wire generates code in:
# - pkg/app/topaz/wire_gen.go
# - pkg/cc/wire_gen.go
```

--------------------------------

### Database Recovery Procedure

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Steps to restore the directory database from a backup file if corruption occurs.

```bash
topaz stop

mv ~/.local/share/topaz/db/topaz.db ~/.local/share/topaz/db/topaz.db.corrupt
topaz directory import < backup.json

topaz start
```

--------------------------------

### Execute Rego Query

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Executes an arbitrary Rego query against the loaded policy. Requires a valid identity context and optional input parameters.

```go
func (s *AuthorizerServer) Query(ctx context.Context, req *authorizer.QueryRequest) (*authorizer.QueryResponse, error)
```

```go
resp, err := authorizerServer.Query(ctx, &authorizer.QueryRequest{
    Query: "data.todoApp.todos_for_user[x]",
    IdentityContext: &api.IdentityContext{
        Type:     api.IdentityType_IDENTITY_TYPE_SUB,
        Identity: "user@example.com",
    },
    Input: `{"todo_id": "123"}`,
    Options: &authorizer.QueryOptions{
        Trace:   authorizer.TraceLevel_TRACE_LEVEL_FULL,
        Metrics: true,
    },
})
if err != nil {
    return err
}
result := resp.Response.AsMap()["result"]
```

--------------------------------

### Kubernetes Database Snapshots

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Backup persistent volumes and export directory data in a Kubernetes environment.

```bash
# Backup PersistentVolumeClaim
kubectl get pvc topaz-data -o yaml > topaz-pvc-backup.yaml

# Create snapshot
kubectl exec -it topaz-0 -- topaz directory export > backup.json
```

--------------------------------

### Discover Topaz environment locations

Source: https://github.com/aserto-dev/topaz/blob/main/docs/config.md

Displays the current XDG-based directory locations used by the Topaz CLI.

```bash
topaz config info environment

{
  "home": "/Users/gertd",
  "xdg_config_home": "/Users/gertd/.config",
  "xdg_data_home": "/Users/gertd/.local/share"
}
```

--------------------------------

### Backup and Restore Directory Database

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Use the topaz CLI to perform hot backups and imports of the BoltDB directory database.

```bash
# Backup (while running, uses hot backup)
topaz directory export --output backup.json

# Restore
topaz directory import --input backup.json
```

--------------------------------

### Configure Kubernetes Readiness Probe

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Defines a gRPC readiness probe for the authorizer service in a Kubernetes manifest.

```yaml
readinessProbe:
  grpc:
    port: 9494
    service: authorizer  # Check specific service readiness
  initialDelaySeconds: 5
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3
```

--------------------------------

### Override Configuration via Environment Variables

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Set configuration values directly in the shell environment before executing the Topaz binary.

```bash
# Set via command line
export TOPAZ_LOGGING_LOG_LEVEL=debug
export TOPAZ_DIRECTORY_DB_PATH=/data/topaz.db
export TOPAZ_AUTH_API_KEY=my-secret-key

topazd run --config-file config.yaml
```

--------------------------------

### Configure Aserto Edge plugin in OPA

Source: https://github.com/aserto-dev/topaz/blob/main/topazd/authorizer/plugins/edge/aserto_edge.md

Define the aserto_edge plugin settings within the OPA configuration file to enable and customize directory synchronization.

```yaml
opa:
  config:

    # plugins section
    plugins:
      aserto_edge:
        enabled: false 
        addr: ""                    # gRPC directory service address.
        apikey: ""                  # directory API key.
        timeout: 5                  # gRPC connection timeout in seconds.
        sync_interval: 1            # sync run interval in minutes.
        insecure: true              # when using TLS connections, skip verification of the server certificate. 
        page_size: 100              # deprecated: no longer used.
        client_cert_path: ""        # when using mTLS connections, ClientCertPath is the path of the client's certificate file.
        client_key_path: ""         # when using mTLS connections, ClientKeyPath is the path of the client's private key file.
        no_tls: false               # disable TLS and use a plaintext connection.
        no_proxy: false             # bypasses any configured HTTP proxy.
        headers:                    # additional headers to include in requests to the service.
```

--------------------------------

### Execute boltdb backup

Source: https://github.com/aserto-dev/topaz/blob/main/topaz-backup/README.md

Performs a backup of the boltdb database file to the specified directory. Must be run on the same machine as the topazd process.

```bash
topaz-backup boltdb \
--db-file ~/.local/share/topaz/db/gdrive-v33.db \
--backup-dir ~/.local/share/topaz/backup

/Users/gertd/.local/share/topaz/backup/gdrive-v33-20250731T162842.db
```

--------------------------------

### Configure Static API Key

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/7-authentication-and-authorization.md

Sets a static API key for authentication within the configuration file.

```yaml
auth:
  api_key: my-secret-key
  api_key_header: Authorization
  api_key_secret: header.api_key
```

--------------------------------

### Configure Kubernetes Liveness Probe

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Defines a liveness probe using an exec command to verify the process is running.

```yaml
livenessProbe:
  exec:
    command:
      - /bin/sh
      - -c
      - kill -0 $$  # Check process running
  initialDelaySeconds: 10
  periodSeconds: 30
  timeoutSeconds: 5
  failureThreshold: 3
```

--------------------------------

### Configure Directory Performance Indices

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/8-deployment-and-operations.md

Adjust batch sizes, page sizes, and request timeouts to optimize directory database operations.

```yaml
directory:
  index:
    batch_size: 1000      # Increase for larger batch operations
    page_size: 100        # Increase for faster sequential reads
  request_timeout: 30s    # Timeout for directory operations
```

--------------------------------

### Define PolicyContext in Go

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/5-types-reference.md

Specify the policy path and the list of decision rules to evaluate.

```go
policy := &api.PolicyContext{
    Path:      "todoApp.GET.todos",
    Decisions: []string{"allowed"},
}

// Evaluate multiple decisions
policy := &api.PolicyContext{
    Path:      "todoApp",
    Decisions: []string{"allowed", "audit_required", "rate_limit"},
}
```

--------------------------------

### Enable Debug Service

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/6-service-lifecycle.md

Configure the debug service to listen on a specific address for profiling.

```yaml
debug_service:
  enabled: true
  listen_address: :9898
```

--------------------------------

### Resolve Identity Context Implementation

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/7-authentication-and-authorization.md

Go implementation for resolving identity and user objects from the context.

```go
func (s *AuthorizerServer) resolveIdentityContext(ctx context.Context, idCtx *api.IdentityContext, input map[string]any) error {
    if idCtx.GetType() != api.IdentityType_IDENTITY_TYPE_NONE {
        input[InputIdentity] = convert(idCtx)
        
        user, err := s.getUserFromIdentityContext(ctx, idCtx)
        if err != nil || user == nil {
            return aerr.ErrAuthenticationFailed.WithGRPCStatus(codes.NotFound).Msg("failed to resolve identity context")
        }
        
        input[InputUser] = convert(user)
    }
    return nil
}
```

--------------------------------

### Query

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/1-authorizer-api.md

Executes an arbitrary Rego query against the loaded policy with optional tracing and metrics.

```APIDOC
## Query

### Description
Executes an arbitrary Rego query against the loaded policy with optional tracing.

### Signature
`func (s *AuthorizerServer) Query(ctx context.Context, req *authorizer.QueryRequest) (*authorizer.QueryResponse, error)`

### Request Fields
- **Query** (string) - Required - Rego query to evaluate
- **IdentityContext** (*api.IdentityContext) - Required - User identity
- **PolicyContext** (*api.PolicyContext) - Optional - Policy context
- **ResourceContext** (*structpb.Struct) - Optional - Resource context
- **Input** (string) - Optional - JSON object string merged into query input
- **Options** (*authorizer.QueryOptions) - Optional - Trace, metrics, and instrumentation settings

### Response
- **Response** (*structpb.Struct) - Query result
- **Trace** ([]*structpb.Struct) - Full trace objects
- **TraceSummary** ([]string) - Trace summary lines
- **Metrics** (*structpb.Struct) - Performance metrics
```

--------------------------------

### File Organization Structure

Source: https://github.com/aserto-dev/topaz/blob/main/_autodocs/INDEX.md

Displays the directory structure of the documentation repository.

```text
output/
├── INDEX.md                          # This file
├── 1-authorizer-api.md               # Authorizer Service API
├── 2-directory-api.md                # Directory Service API
├── 3-opa-builtins.md                 # OPA Built-in Functions
├── 4-configuration.md                # Configuration Schema
├── 5-types-reference.md              # Data Types and Structures
├── 6-service-lifecycle.md            # Service Initialization & Lifecycle
├── 7-authentication-and-authorization.md  # Auth Configuration
└── 8-deployment-and-operations.md    # Production Deployment
```