Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.neuraltrust.ai/llms.txt

Use this file to discover all available pages before exploring further.

After installing AI Gateway, the next step is to create your first gateway instance. This guide will walk you through creating and configuring a basic gateway.

​
Before you begin: Generate an Admin JWT

To interact with the Admin API (control plane), you need a valid JWT. Use the repository script to generate it: Script: scripts/generate_jwt_token.sh Requirement: The environment variable SERVER_SECRET_KEY must be set, and it must be exactly the same value used when starting TrustGate. If these differ, the generated JWT will be rejected by the control plane. Example:
  1. Set the server secret (must match the value used to start TrustGate): export SERVER_SECRET_KEY="your-secure-shared-secret"
  2. Generate the admin JWT (the script prints a token to stdout; you can capture it into an env var): export ADMIN_JWT=$(bash scripts/generate_jwt_token.sh)
  3. Use the token in Admin API requests, e.g.: curl -H "Authorization: Bearer $ADMIN_JWT" http://localhost:8080/api/v1/gateways
Note: The examples below use an Authorization header placeholder. Replace it with your real token, for example: -H "Authorization: Bearer $ADMIN_JWT".
Use the Admin API to create your first gateway:
# Create a gateway
curl -X POST http://localhost:8080/api/v1/gateways \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer jwt example" \
  -d '{
    "name": "my-first-gateway",
    "subdomain": "api",
    "required_plugins": [
        {
            "name": "rate_limiter",
            "enabled": true,
            "stage": "pre_request",
            "priority": 1,
            "settings": {
                "limits": {
                    "global": {
                        "limit": 15,
                        "window": "1m"
                    },
                    "per_ip": {
                        "limit": 5,
                        "window": "1m"
                    },
                    "per_user": {
                        "limit": 5,
                        "window": "1m"
                    }
                },
                "actions": {
                    "type": "reject",
                    "retry_after": "60"
                }
            }
        }
    ]
  }'

​
Verify Gateway Creation

Check if your gateway was created successfully:
# Get gateway details
curl http://localhost:8080/api/v1/gateways/{gateway-id} \
  -H "Authorization: Bearer jwt example"

# List all gateways
curl http://localhost:8080/api/v1/gateways \
  -H "Authorization: Bearer jwt example"

curl -X POST http://localhost:8080/api/v1/gateways/{gateway-id}/upstreams \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer jwt example" \
  -d '{
    "name": "ai-providers-upstream",
    "algorithm": "round-robin",
    "targets": [
      {
        "path": "/v1/chat/completions",
        "provider": "openai",
        "weight": 50,
        "priority": 1,
        "default_model": "gpt-4o-mini",
        "models": ["gpt-3.5-turbo", "gpt-4", "gpt-4o-mini"],
        "credentials": {
          "header_name": "Authorization",
          "header_value": "Bearer your-openai-key"
        }
      },
      {
        "path": "/v1/messages",
        "provider": "anthropic",
        "weight": 50,
        "priority": 1,
        "default_model": "claude-3-5-sonnet-20241022",
        "models": ["claude-3-5-sonnet-20241022"],
        "headers": {
          "anthropic-version": "2023-06-01"
        },
        "credentials": {
          "header_name": "x-api-key",
          "header_value": "your-anthropic-key"
        }
      }
    ],
    "health_checks": {
      "passive": true,
      "threshold": 3,
      "interval": 60
    }
  }'

​
Verify Configuration

Check that your upstream is properly configured:
curl http://localhost:8080/api/v1/gateways/{gateway-id}/upstreams/{upstream-id} \
  -H "Authorization: Bearer jwt example"
Create your service using the Admin API:
curl -X POST http://localhost:8080/api/v1/gateways/{gateway-id}/services \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer jwt example" \
  -d '{
    "name": "my-service",
    "upstream_id": "{upstream-id}",
    "type": "upstream",
    "description": "My Service"
  }'

​
Verify Configuration

Check that your service is properly configured:
curl http://localhost:8080/api/v1/gateways/{gateway-id}/services/{service-id} \
  -H "Authorization: Bearer jwt example"
Create your first rule using the Admin API:
# Exact matching
curl -X POST http://localhost:8080/api/v1/gateways/{gateway-id}/rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer jwt example" \
  -d '{
    "service_id": "{service-id}",
    "path": "/test",
    "methods": ["POST"],
    "strip_path": false,
    "preserve_host": false
  }'

​
Verify Rules

Check that your rules are properly configured:
curl http://localhost:8080/api/v1/gateways/{gateway-id}/rules \
  -H "Authorization: Bearer jwt example"
Test your rule configurations:API Key (optional): If you plan to use API key authentication, create one in the Final Step below and set the X-TG-API-Key header to your key.
# Test a route
curl -X POST http://localhost:8080/test \
  -H "Content-Type: application/json" \
  -H "X-TG-API-Key: your-key" \
  -H "Authorization: Bearer jwt example" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true,
    "stream_options": {
      "include_usage": true
    },
    "max_tokens": 1024
  }'

# Create an API key for your gateway and rule
curl -X POST {{admin_host}}/api/v1/iam/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer jwt example" \
  -d '{
    "name": "test-key",
    "expires_at": "2026-01-01T00:00:00Z",
    "subject_type": "gateway",
    "subject": "{{gateway_id}}",
    "policies": ["{{rule_id}}"]
  }'

​
Next steps:

Now that you have configured your rules, read more about:

​
Troubleshooting

Common issues and solutions:
  1. Routing Issues
  • Verify path patterns
  • Check method restrictions
  • Review rule priorities
  1. Path Handling
  • Check strip_path setting
  • Verify preserve_host
  • Test path transformations
  1. Header Problems
  • Verify header requirements
  • Check header values
  • Test header matching