> ## 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 LibreChat

> Create a virtual account for LibreChat, grant it provider-qualified models, and store its token as a Kubernetes secret.

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

> [!WARNING]
>
> 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.](https://mintcdn.com/truefoundry/fqJXGOrZ4JcvbYVx/images/ai-gateway/librechat-grant-gate-light.svg?fit=max\&auto=format\&n=fqJXGOrZ4JcvbYVx\&q=85\&s=7dfbda0d32678576eb09a1a1733ae103)

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](https://www.truefoundry.com/docs/ai-gateway/librechat/install-helm.md#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:

```bash theme={"dark"}
read -rs TFY_TOKEN && echo
kubectl -n librechat create secret generic librechat-gateway-key \
  --from-literal=TFY_GATEWAY_KEY="$TFY_TOKEN"
unset TFY_TOKEN
```

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](https://www.truefoundry.com/docs/ai-gateway/librechat/install-helm.md#create-the-namespace-and-the-app-secret) covers it.

Expected output:

```text theme={"dark"}
secret/librechat-gateway-key created
```

Check that the key is present, without printing its value:

```bash theme={"dark"}
kubectl -n librechat get secret librechat-gateway-key \
  -o jsonpath='{.data}' | python3 -c "import sys,json;print(sorted(json.load(sys.stdin)))"
```

Expected output:

```text theme={"dark"}
['TFY_GATEWAY_KEY']
```

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


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