Usage

• 1: User and Identity Setup
• 2: Connecting to the Gateway

1 - User and Identity Setup

AI Gateway accepts a verified JWT as the caller’s identity. Choose one of these identity setups:

• Use a PPC user when your deployment uses PPC authentication.
• Configure an external identity provider (IdP) when callers authenticate through an issuer such as Keycloak or Microsoft Entra ID.

Regardless of issuer, send the identity JWT to the gateway in the x-user-auth request header. The gateway validates it against the configured IdP trust registry.

PPC User Setup

Before client applications can call the gateway with a PPC-issued identity, the PPC role must grant gateway access and the user must be assigned that role.

1. Set the PPC URL and obtain an authentication token

1. Set the PPC URL using the following command:

export PPC_URL="https://<PPC_FQDN>"

2. Obtain an authentication token.

2. Add the gateway permission to the PPC role, preserving any permissions the role already requires.

curl -sS -X PUT "${PPC_URL}/pty/v1/auth/roles" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<PPC_ROLE>",
    "description": "Role for AI Gateway access",
    "permissions": ["can_create_token", "ai_gateway_access"]
  }'

3. Create a PPC user

curl -sS -X POST "${PPC_URL}/pty/v1/auth/users" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "<USERNAME>",
    "email": "<USER_EMAIL>",
    "firstName": "<FIRST_NAME>",
    "lastName": "<LAST_NAME>",
    "password": "<INITIAL_PASSWORD>",
    "roles": ["<PPC_ROLE>"]
  }'

Replace all placeholders with values for your PPC deployment. Use your organization’s password policy and secure credential-handling process.

Verify in the PPC administration interface that the role includes ai_gateway_access and that the new user is assigned that role. Then obtain the user’s identity JWT through your configured identity flow and test a request using the x-user-auth header as shown in Connecting to the Gateway.

External IdP Setup

The gateway trusts external issuers through an IdP registry file, idp.yaml. For each request, it reads the JWT from the header named by FG_PRINCIPAL_TOKEN_HEADER (default: x-user-auth), selects the issuer by the token’s iss claim, verifies the signature, and checks the configured issuer, audience, and expiration before mapping claims to the principal context.

Set the following gateway environment variables:

Example idp.yaml for an issuer with a JWKS endpoint:

issuers:
  - iss: "<IDP_ISSUER_URL>"
    idp: keycloak
    jwks_url: "<IDP_JWKS_URL>"
    audience: "<EXPECTED_AUDIENCE>"
    # Optional overrides for non-standard claim names:
    # user_id_claim: sub
    # roles_claim: realm_access.roles

Set iss to the exact issuer value in the JWT. Prefer jwks_url, which supports signing-key rotation. The gateway has claim-mapping defaults for keycloak, entra, and generic; override them only when the issuer uses non-standard claims. Supply a valid issuer-specific token to verify the configuration using the Connecting to the Gateway instructions.

2 - Connecting to the Gateway

Configure client applications to send requests through the AI Gateway. The gateway API base URL is <GATEWAY_HOST>/pty/federated-guardrails/v1; the client library appends its endpoint path.

Every request must include the caller’s verified identity JWT in x-user-auth. The optional x-team-id header selects a profile according to the deployment’s routing configuration. For example, the sample policy routes cs-bot to simple-protection, dps-bot to dps-protection, dpsl-bot to dpsl-protection, sdc-bot to sdc-protection, and gai-bot to gai-protection; requests without a matching header use the configured default profile.

1. Set the Gateway URL and Identity Token

Obtain an access token from the identity provider configured for your gateway. Set the gateway host and token for the examples:

export GATEWAY_BASE_URL="https://<GATEWAY_HOST>/pty/federated-guardrails/v1"
export IDENTITY_TOKEN="<IDP_ACCESS_TOKEN>"
export TEAM_ID="cs-bot"

Do not use a PPC token response header as the identity header value unless that token is the JWT issued for the caller and trusted by the gateway’s IdP registry.

2. Send an OpenAI-Compatible Request

The OpenAI SDK sends the identity and profile headers with each request. The client api_key is not the upstream credential for the OpenAI configuration shown here; the gateway uses its configured upstream key.

import os

import httpx
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["GATEWAY_BASE_URL"],
    api_key="unused",
    default_headers={
        "x-user-auth": os.environ["IDENTITY_TOKEN"],
        "x-team-id": os.environ["TEAM_ID"],
    },
    http_client=httpx.Client(),
)

reply = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello from the gateway."}],
)
print(reply.choices[0].message.content)

The OpenAI SDK appends /chat/completions to the configured base URL. To test without the SDK:

curl -X POST "${GATEWAY_BASE_URL}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "x-user-auth: ${IDENTITY_TOKEN}" \
  -H "x-team-id: ${TEAM_ID}" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello from the gateway."}]
  }'

3. Send an Anthropic Request

Configure the gateway’s YAML policy with upstream.protocol: anthropic and the Anthropic upstream URL. The Anthropic SDK appends /v1/messages to the same gateway base URL.

Important: In the current gateway image, the Anthropic protocol forwards the client’s x-api-key upstream. Supply a valid Anthropic API key in the SDK; unlike the OpenAI example, a placeholder client key will not work.

import os

import httpx
from anthropic import Anthropic

client = Anthropic(
    base_url=os.environ["GATEWAY_BASE_URL"],
    api_key=os.environ["ANTHROPIC_API_KEY"],
    default_headers={
        "x-user-auth": os.environ["IDENTITY_TOKEN"],
        "x-team-id": os.environ["TEAM_ID"],
    },
    max_retries=0,
    http_client=httpx.Client(),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=[{"role": "user", "content": "Hello from the gateway."}],
)
print(message.content[0].text)

To verify the connection, confirm that the SDK returns a response and that the gateway logs show the request being routed to the expected profile. Use a trusted CA certificate in production; do not disable TLS certificate verification.