Skip to main content

Connect a client

Opt your organization in to the AI Gateway, manage its budget, and set up Claude Code, Codex CLI, OpenCode, Claude Desktop and other tools with your Hatz API key.

Connect a client is the page in Settings, next to API Keys, where you set up coding tools and SDKs to use Hatz models with your Hatz API key. It also shows your organization's AI Gateway budget, and it's where a tenant admin opts the organization in to the AI Gateway.

Availability: The page has something to set up only after your MSP has activated the AI Gateway. Until then it shows Nothing to configure yet. Your MSP can activate it under Settings → AI Gateway in the admin console.

Before you start

  • You need the Use LLM Gateway permission. If the page shows Access Restricted, ask an administrator to add it to your role.

  • You need a Hatz API key. See API Keys.

  • Your organization must have opted in to the AI Gateway. Until it has, the Connect a client button on this page is turned off and API requests to these endpoints are refused, unless your organization keeps legacy credits.

Opt your organization in

Opting in needs the Manage tenant LLM Gateway permission, which the built-in Client Admin role includes. Other members see the notice and "An administrator of your organization can opt in." Your MSP admin can also opt your organization in for you.

  1. Open Settings → Connect a client. The AI Gateway budget card shows Off, or On credits (legacy) if your organization keeps legacy credits.

  2. Read the notice. Opting in means your organization's requests to the Anthropic Messages and OpenAI Responses endpoints are billed in USD, at provider rates plus the Hatz fee, instead of in credits. A monthly budget applies immediately.

  3. Select I accept this notice for my organization. and click Turn on, or Switch to USD billing if your organization keeps legacy credits.

Opting in can't be undone. Your organization can't switch back to Hatz credits for these endpoints. Hatz chat, agents, Workshop and the Chat Completions API stay on credits.

Your organization's budget

The AI Gateway budget card shows your monthly budget, the most your MSP allows, and what's been spent this month. Members see it read-only.

  • To change it, a tenant admin enters a New monthly budget (USD) and clicks Save budget. It can't be higher than the maximum your MSP allows.

  • Changes apply to the next request, and may pause your organization's requests for a moment.

  • A budget below this month's spend stops new requests until the next month. Requests already running finish.

  • Budgets reset at the start of each calendar month in UTC.

When the budget is used up, requests are refused until it's raised or the next month starts. Your MSP's combined cap for all tenants can also stop requests before your own budget is used up.

Set up a tool

Choose a tool, copy its setup prompt, and paste it into your coding assistant. The page has setup for:

  • Claude Code, Codex CLI, OpenCode and Pi (terminal tools)

  • Hermes

  • Claude Desktop

  • The OpenAI Responses SDK and the Anthropic SDK

  1. Pick your system: macOS / Linux (bash or zsh), Windows PowerShell, or Windows Command Prompt. The page suggests one based on your computer.

  2. Click Setup prompt, then Copy, and paste the prompt into your coding assistant. The prompt never contains your API key. Where it shows YOUR_HATZ_API_KEY, add your key yourself in your terminal or settings file. Don't paste your key into the chat with your assistant.

  3. To do it yourself instead, open Set up manually for the exact commands and settings. You can paste your key into Your Hatz API key (optional) to fill it into the commands. It stays in your browser and isn't saved. Run commands that contain your key yourself; don't paste them into an assistant chat.

Claude clients, such as Claude Code and Claude Desktop, fetch the list of models your key can use automatically. The OpenAI Responses setup works with the Responses API only; Chat Completions isn't available through it and stays on Hatz credits.

Check your account is ready

Expand Test gateway connection and click Run check. It checks your signed-in account, permissions, billing state and model access, and says how many models are available to you. It doesn't test a pasted API key. No request is sent to the model provider, so nothing is billed.

After you create an API key

When you generate a key on API Keys, the confirmation screen shows Use this key with Claude Code, Codex and more. Click Connect a client to open the setup page, or open Or set it up here with this key already filled in to see the manual setup with your new key.

Troubleshooting

  • The page says Nothing to configure yet. Your MSP hasn't activated the AI Gateway, or hasn't finished setting it up. Contact your MSP if it stays this way.

  • The page says Gateway access is suspended. Your MSP's AI Gateway is suspended. Contact your MSP.

  • The Connect a client button on this page is turned off. Your organization hasn't opted in. A tenant admin can opt in on this page.

  • The page says Disabled by your provider. Your MSP has turned off AI Gateway access for your organization. Your API keys and budget are kept. Contact your MSP to restore it.

  • The page says Access Restricted. Ask an administrator to add the Use LLM Gateway permission to your role.

  • A tool shows an error that mentions LLM Gateway. See AI Gateway errors in the FAQs / Troubleshooting collection.

Related articles

Did this answer your question?