Skip to main content
GATEKEEPER
Getting Started

Quick start

Start a credential-injecting proxy in under five minutes.

Prerequisites

  • Go 1.25+ installed
  • gatekeeper binary on $PATH (see Installation)
  • openssl available (for CA generation)

Step 1: Generate a CA certificate

The proxy needs a CA to sign per-host TLS certificates. Use the included script:

cd examples && ./gen-ca.sh

This creates ca.crt and ca.key in the examples/ directory.

Step 2: Write a minimal config

Create gatekeeper.yaml:

proxy:
  host: 127.0.0.1
  port: 9080

tls:
  ca_cert: examples/ca.crt
  ca_key: examples/ca.key

credentials:
  - host: api.example.com
    header: Authorization
    grant: example-api
    source:
      type: env
      var: EXAMPLE_API_TOKEN

network:
  policy: permissive

log:
  level: info
  format: text

This configures the proxy to inject the value of the EXAMPLE_API_TOKEN environment variable as an Authorization header on all requests to api.example.com.

Step 3: Start the proxy

Set the credential and start gatekeeper:

export EXAMPLE_API_TOKEN="sk-xxxx"
gatekeeper --config gatekeeper.yaml

The proxy logs a startup message:

level=INFO msg="gatekeeper listening" addr=127.0.0.1:9080 version=dev

Step 4: Make a request through the proxy

In a separate terminal, send a request through the proxy:

curl --proxy http://127.0.0.1:9080 --cacert examples/ca.crt \
  https://api.example.com/v1/resource

The --proxy flag routes the request through gatekeeper. The --cacert flag trusts the generated CA so curl accepts the intercepted TLS certificate.

Gatekeeper intercepts the connection, injects the Authorization: Bearer sk-xxxx header, and forwards the request to api.example.com. The credential never appears in the curl command or the client environment of the calling process.

Step 5: Verify credential injection

The proxy logs each request with credential injection details:

level=INFO msg=request http_method=GET http_host=api.example.com http_path=/v1/resource http_status=200 duration_ms=142 credential_injected=true injected_headers=Authorization grants=example-api

The credential_injected=true and grants=example-api fields confirm the proxy injected the credential.

Next steps