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. Start with a letter, end with a letter or digit, 3 to 36 characters. Example:
librechat-gw. - Expiration date (UTC). Choose 30, 90 or 365 days, or enter a date. Use a short expiry for an evaluation. For production, use a longer expiry and turn on auto-rotation.
- Owner of the virtual account. Optional. Set it to the team that runs LibreChat.
- 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>.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.
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. The list shows each model with its provider account in small text. 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.
Use the provider-qualified model ID
Use the full ID that includes the provider prefix, for exampleazure-openai-main/o4-mini, in LibreChat 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>.
Store the token in the cluster
LibreChat reads the token from the environment variableTFY_GATEWAY_KEY. Store the token in a Kubernetes secret, and let the chart load it from there. The token never goes into a values file, a chart, or your shell history.
Read the token without echoing it, then create the secret in the librechat namespace:
read -rs prompt. The -s flag keeps it off the screen and out of the history file. Create the namespace first if it does not exist yet. Install and verify covers it.
Expected output: