> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway access for Open WebUI

> Create a virtual account for Open WebUI, grant it a provider-qualified model, and copy its token.

Open WebUI calls the gateway with a virtual account. The account has one token. Its grants decide which models the token can call. This page creates the account, grants a model, and copies the token for the container.

Create one virtual account per application. You can then rotate or revoke one app's token without touching the others, and the gateway logs show which app made each call.

## Create the virtual account

**1. Open virtual accounts**

In the TrueFoundry console, open **Access Management → Virtual Accounts**, under **For Applications**.

**2. Start a new account**

Click **New Virtual Account**.

**3. Fill in the form**

* **Name.** Lowercase letters, digits and hyphens. Example: `openwebui-gw`.
* **Expiration date (UTC).** Optional. Choose 7, 14, 30, 90 or 365 days, or enter a date. An expiry cannot be edited later, so leave it empty for an account that should live indefinitely.
* **Owner of the virtual account.** Optional. Set it to the team that runs Open WebUI.
* **Enable auto rotation** and **Enable notification.** Optional. Turn both on for production.

**4. Generate the account**

Click **Generate Virtual Account**. The console shows **Virtual account created successfully** and the token, in the form `tfy_va_<name>_<secret>`. The dialog offers **Configure Access Now** and **Do it later**. Choose **Configure Access Now** to grant a model next.

> [!WARNING]
>
> The token is shown once in this dialog. Copy it now, or download it. The **Get token** action in the token list can show it again while the token is active. If the token is lost or regenerated, every app that uses the old one stops working.

The new account has no access yet. Every call from it returns `403` until you add a grant. The **Permissions** column in the list shows a dash for an account without grants.

## Grant a model

A grant names one model and one role. For model access, use the role **Provider Integration Access**. The gateway checks each request against the grants on the token. A request for a model without a matching grant returns `403`, even when the model is listed by `/models`.

![Flow diagram. Three requests reach the gateway grant check. A request for azure-openai-main/o4-mini, the provider-qualified ID that the key has been granted, returns 200. A request for openai-main/gpt-4o-mini, which the key has not been granted, returns 403. A bare name, o4-mini, with no provider prefix, also returns 403: the grant is on the provider-qualified ID, so a bare name is a different request.](https://mintcdn.com/truefoundry/u9A7Ha_L6d5kXr6t/images/ai-gateway/openwebui-grant-gate-light.svg?fit=max\&auto=format\&n=u9A7Ha_L6d5kXr6t\&q=85\&s=a8af7154bbd8b14751d7586f28a08040)

A grant applies to one provider-qualified model ID. A bare name is a different request.

**1. Open the account's permissions**

In **Access Management → Virtual Accounts**, open the row menu for the account and choose **Manage Permissions**. The same drawer opens from **Configure Access Now** right after creation.

**2. Add a permission**

Under **Granted Permissions**, click **Add Permission**. In the resource type list, choose **Models**.

**3. Pick the model and its provider**

Type the model name in **Resources**. Each option shows the model name, with its provider account in small text under it. The same model name often exists under several providers, and each one is a separate route. Read the provider name before you tick the box.

**4. Keep the role and save**

Leave **Provider Integration Access** selected under **Select a Role**, then click **Save**. The console confirms with **Permission granted**.

The grant appears in the **Granted Permissions** table with the model name, the provider account under it, the role **Provider Integration Access**, and the type **Models**. If the provider shown is not the one you expected, delete the row with the trash icon and add the correct one. A deletion takes effect at once.

### Use the provider-qualified model ID

Use the full ID that includes the provider prefix, for example `azure-openai-main/o4-mini`, in Open WebUI and in every check. Do not use the bare name.

The difference matters:

* A bare name such as `o4-mini` is refused with `403`, because the grant is on the provider-qualified ID.
* A bare name can also resolve to a provider account that does not serve the model. The call then returns `400` with `not found in model account <provider>`.

To list the exact IDs your token can use, see [Check the gateway path](https://www.truefoundry.com/docs/ai-gateway/open-webui/install-docker.md#check-the-gateway-path).

## Copy the token

Open WebUI reads the token from the environment variable `OPENAI_API_KEY`. Write it into an env file with the base URL, and keep the file readable only by you. The token then never appears in a shell history or on a command line.

Use the **Get token** action on the active token. Copy the value into the env file in [Install with Docker](https://www.truefoundry.com/docs/ai-gateway/open-webui/install-docker.md#write-the-env-file).

> [!NOTE]
>
> Each row in the token list shows its status. A token marked **ACTIVE** is the one to copy. A token marked **EXPIRING SOON** is the old one after a regenerate, and it stops working on its expiry time. Copy from the **ACTIVE** row only.

To rotate the token later, see [Rotate the token](https://www.truefoundry.com/docs/ai-gateway/open-webui/operate.md#rotate-the-token).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.