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.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 returns403, even when the model is listed by /models.
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.
Use the provider-qualified model ID
Use the full ID that includes the provider prefix, for exampleazure-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-miniis refused with403, 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
400withnot found in model account <provider>.
Copy the token
Open WebUI reads the token from the environment variableOPENAI_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.