# AI Gateway User Apps

A User App lets people call the AI Gateway with their own API key. Instead of
creating an [app](./apps.mdx) for every person who wants to use AI in their
everyday tools, everyone with access to the project calls one shared URL with a
personal key. The gateway knows who made each request, applies that person's
budget, and reports their usage.

Use an app for software and the User App for people. A support chatbot or a
nightly batch job is an app, with its own API key, in a [pool](./pools.mdx). An
engineer using Claude Code or Codex is a person, and calls the User App with a
personal key.

Each AI Gateway project has one User App, created for you. A new project gets it
right away; an existing project gets it on its next production deployment. A
project connected to source control also needs the User App route in its
repository—see
[Keep the gateway up to date](./source-control.mdx#keep-the-gateway-up-to-date).
It has:

- **A URL** under `/u/`, such as
  `https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64`.
  Everyone calls the same URL.
- **Personal API keys**—each person creates their own. A personal key works only
  on the User App URL, and an app's API key doesn't work there.
- **A per-person budget**—an optional spending allowance, such as $50 per day,
  that applies to each person separately.
- **A [policy chain](./policy-chains.mdx)**—the policies that run on every
  request made with a personal key.

The User App isn't part of a pool. Pool budgets and policy templates apply to
apps; [gateway-wide usage limits](./usage-limits.mdx) apply to both.

## Setting up the User App

Only Admins set up the User App: they choose who can use it, set its budget, and
edit its policies. With the role-based access control (RBAC) add-on, that means
project or account **Admins**; Developers, Members, and AI Users can use the
User App but can't change its budget or policies. Without RBAC, every account
member is an Admin.

Admins manage the User App on the AI Gateway project's
[**Users**](https://portal.zuplo.com/+/account/project/ai/users) tab.

<Stepper>

1. **Give people access.** Everyone with a role on the AI Gateway project—Admin,
   Developer, Member, or AI User—can use the User App.

   With RBAC, to give someone access to the User App and nothing else, open
   [**Settings** > **Members & Access**](https://portal.zuplo.com/+/account/project/ai/settings/members)
   on the AI Gateway project, click **Add to project**, enter their email, and
   choose the **AI User** role. Someone who isn't in your Zuplo account yet is
   added to it as a **Member**. An AI User can call the User App and see their
   own keys and usage, but not the rest of the project's configuration or anyone
   else's usage. See
   [Managing Project Members](../articles/accounts/managing-project-members.mdx)
   and [Role Permissions](../articles/accounts/roles-and-permissions.mdx).

1. **Set a per-person budget.** The User App starts with no budget. Open
   **Budgets** and set how much each person can spend **Per person per day** and
   **Per person per month**, such as $50 and $100. Each person gets the full
   amount, counted separately.

   :::caution{title="Set a budget to limit spend"}

   Until you set a budget, the gateway tracks what each person spends through
   the User App, and **People** shows it, but nothing limits it. A budget you
   add partway through a day or month counts what each person already spent in
   that period.

   :::

1. **Review the policies.** **Policies** edits the User App's policy chain, such
   as which models people can use. The same policies as an app's
   [policy chain](./policy-chains.mdx) are available.

</Stepper>

**People** lists everyone on the project, how many personal keys each person
has, and what each person spent today and this month. **Gateway** shows the User
App's name, which you can change, its configuration ID, and its URL.

### Personal budgets

To give one person a different amount from everyone else, an Admin clicks the
**Budget** button on the person's row in **People**. **Per day** and **Per
month** always appear; **Per hour** and **Per week** appear only when the User
App's budget limits them. For each period, choose:

- **Default**, shown with the User App's amount, such as **Default · $50**. The
  person's limit follows the User App's amount, including when you change it
  later.
- **Custom** to set an amount for this person only, such as $200 per day for a
  heavy user. Everyone else keeps the User App's amount.

A period that has no User App amount shows **No limit**, and you can't set a
custom amount for it until you set one on **Budgets**. While anyone has a custom
amount for a period, you can't remove that period's amount from **Budgets**;
switch those people back to the default first.

Click **Save** to apply the change. To remove all of a person's custom amounts,
click **Use all defaults** and confirm. Changing a budget never resets what the
person has already spent in the current period.

## Using the User App

<Stepper>

1. **Create a personal API key.** Open the AI Gateway project in the Zuplo
   Portal and go to the
   [**Home**](https://portal.zuplo.com/+/account/project/ai/home) tab. Under
   **My API keys**, click **New key**, give it a name such as `Laptop CLI`, and
   copy the key.

1. **Call the gateway.** Copy the **Gateway URL** shown at the top of the
   **Home** tab once the gateway has a production deployment—the User App's
   `/u/` URL—and use it with your personal key in place of the provider's base
   URL and API key. The **Home** tab also shows setup steps for common tools
   such as Claude Code and Codex.

</Stepper>

For example, to call the Chat Completions endpoint with `curl`:

```bash
curl https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64/v1/chat/completions \
  -H "Authorization: Bearer $ZUPLO_PERSONAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'
```

The User App serves the same [endpoints](./universal-api.mdx) as an app—**Chat
Completions**, **Responses**, and **Messages**. The integration guides for
[Claude Code](./integrations/claude-code.mdx),
[Codex](./integrations/codex.mdx),
[Claude Desktop](./integrations/claude-desktop.mdx),
[GitHub Copilot](./integrations/github-copilot.mdx), and
[goose](./integrations/goose.mdx) start from your Gateway URL and personal key.

The **Home** tab also shows your allowance and what you've spent against it. If
no budget is set, it says your requests have no personal spending limit. Once
you reach your allowance, the gateway refuses requests with
`429 Too Many Requests` until the period resets or an Admin raises your budget.

## Removing access

A personal key works only while its owner has access to the AI Gateway project.
When someone loses access to the project, or is removed from the Zuplo account,
their personal keys for that project are deleted and stop working within
seconds. You don't need to rotate any keys.

**Additional Resources**

- [Apps](./apps.mdx) - Apps for services and integrations, each with its own API
  key.
- [Role Permissions](../articles/accounts/roles-and-permissions.mdx) - Details
  on the AI User role and other Zuplo account and project roles.
- [Usage Limits](./usage-limits.mdx) - Gateway-wide limits that apply to every
  request.