Public Guide

Set Up AI Gateway for Your Team

Use `/ai-gateway` as the setup home: connect one BYOK provider key, allowlist it in policy, then create a client for your IDE or automation. Audience: Tenant admins, security leads, and workspace owners. Typical setup time: 15-20 minutes.

reference

Use this if

Use `/ai-gateway` as the setup home: connect one BYOK provider key, allowlist it in policy, then create a client for your IDE or automation.

Audience: Tenant admins, security leads, and workspace ownersTypical time: 15-20 minutes

Before You Begin

  • Choose the first provider, IDE, or automation flow you want to pilot through AI Gateway.
  • Confirm which MCP tools users are allowed to see and which provider slugs are approved.
  • Collect the callback URL or client setup details your IDE or agent expects before you create the client.

Guide walkthrough

1

Step 1

Connect one provider first

Start in `/ai-gateway`, then open the OpenAI provider connection to add the first tenant-owned key your team already trusts.

  • Use `/integrations/ai_openai` for the first BYOK provider credential unless your pilot explicitly needs Anthropic or an OpenAI-compatible endpoint.
  • Use a dedicated provider key for BlackShield instead of a personal key shared between people.
  • Run provider preflight before returning to AI Gateway.

What success looks like

Run provider preflight before returning to AI Gateway.

2

Step 2

Allowlist the provider in policy

The AI Gateway restricts active routing and access until policy explicitly allows the connected provider.

  • Open the policy tab from `/ai-gateway` and add the connected provider to `approved_providers`.
  • Keep the first policy simple: provider allowlist, hidden tools, and a clear request limit.
  • Stay in advisory until the pilot team sees the warnings you expect, then move to enforce.

What success looks like

Stay in advisory until the pilot team sees the warnings you expect, then move to enforce.

3

Step 3

Create a client for the tool your team uses

Give each IDE, MCP client, or service principal its own AI Gateway client so access is easy to rotate or disable.

  • Create a public client for sign-in flows or a confidential client for headless automation.
  • Add the callback URL your IDE or agent requires before you hand the client to end users.
  • Limit each client to the provider connections and MCP tools that team actually needs.

What success looks like

Limit each client to the provider connections and MCP tools that team actually needs.

4

Step 4

Test the gateway before broad rollout

Run one low-risk test first so you can confirm auth, policy behavior, and activity logging.

  • Set the MCP endpoint to `/api/v1/mcp` and the inference endpoint to `/api/v1/ai-gateway/openai/v1/chat/completions`.
  • Sign in with the new client or exchange client credentials for a short-lived token.
  • Run `tools/list` or a simple read-only prompt, then confirm the event appears in AI Gateway activity.
  • Review policy warnings and usage logs before inviting more users.

What success looks like

Review policy warnings and usage logs before inviting more users.

Demonstration only

This configuration is designed for ease of use. To deploy scanner clients at scale, please plan your deployment architecture accordingly or contact us for enterprise best practices.

Run This

Exchange client credentials for a short-lived token
curl -X POST https://api.blackshield.chaplau.com/api/v1/ai-gateway/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'
Query OpenAI completions via the Gateway Proxy
curl -X POST https://api.blackshield.chaplau.com/api/v1/ai-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer <your_short_lived_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "List the security requirements for the tenant onboarding flow."
      }
    ]
  }'
Configure the Stdin/Stdout MCP Proxy in Cursor / VS Code / Claude Desktop
{
  "mcpServers": {
    "blackshield-gateway": {
      "command": "blackshield-mcp",
      "args": [
        "--client-id", "<your-client-id>",
        "--client-secret", "<your-client-secret>",
        "--url", "https://api.blackshield.chaplau.com/api/v1/mcp"
      ]
    }
  }
}

What success looks like

  • The pilot client can authenticate and only sees the providers and tools you intended to allow.
  • Gateway activity shows a successful test request and any warnings or denies you expected from policy.
Set Up AI Gateway for Your Team | BlackShield Docs