Skip to main content
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
⌘I