Skip to main content
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.
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.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.

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.

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.
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.