Skip to main content
LibreChat 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 stores the token where LibreChat can read it. 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. 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>.
The token is shown once. Copy it now, or download it. If you lose it, you must regenerate the token, and 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 azure-openai-main/gpt-4o, 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 azure-openai-main/gpt-4o, 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.
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.
The grant appears in the Granted Permissions table with the model name, the provider account under it, the role, 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 LibreChat 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 Verify the gateway path.

Store the token in the cluster

LibreChat reads the token from the environment variable TFY_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:
Paste the token at the 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:
Check that the key is present, without printing its value:
Expected output:
To rotate the token later, see Rotate the token.