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

# Operate Open WebUI on the gateway

> Rotate or revoke the virtual-account token, back up and upgrade the data volume, remove the install, and fix the common errors.

This page covers the work after the first chat: rotating the token, revoking access, upgrading Open WebUI without losing data, and removing the install. The troubleshooting table at the end lists the errors that the gateway and Open WebUI return most often.

## Rotate the token

Regenerate the token when it may have leaked, or on a schedule. Regenerating creates a new token and keeps the old one for a short grace period. The old token is shown with **EXPIRING SOON** and expires on its own.

**1. Regenerate the token**

In **Access Management → Virtual Accounts**, open the account's token list, then click **Regenerate token**.

**2. Copy the new token**

On the row marked **ACTIVE**, click **Get token**, then copy the value. Do not copy from the **EXPIRING SOON** row.

**3. Replace the token in the env file**

Rewrite `openwebui.env` with the new value, using the same `read -rs` method as [Write the env file](https://www.truefoundry.com/docs/ai-gateway/open-webui/install-docker.md#write-the-env-file).

**4. Recreate the container**

The container reads its environment at start-up, so recreate it. The volume keeps your data.

```bash theme={"dark"}
docker rm -f open-webui
docker run -d --name open-webui \
  -p 3000:8080 \
  --env-file openwebui.env \
  -v open-webui-data:/app/backend/data \
  ghcr.io/open-webui/open-webui:v0.13.4
```

**5. Check the gateway**

Run the four checks in [Check the gateway path](https://www.truefoundry.com/docs/ai-gateway/open-webui/install-docker.md#check-the-gateway-path). The models list and the granted call return `200`. The ungranted call returns `403`.

> [!WARNING]
>
> The old token works until its grace period ends. Copy the new token into the env file and restart the container before that time, or chats stop with `401`.

## Revoke access

To cut off Open WebUI at once, delete the token or the whole account. Both stop calls at the gateway, with no change in Open WebUI, which then shows errors on the next chat.

* **One grant.** In **Manage Permissions**, delete the row with the trash icon. Calls for that model return `403` at once. Other grants keep working.
* **One token.** In the token list, delete the token with the trash icon. Calls made with it stop working.
* **The account.** Delete the virtual account from its row menu (**More actions**). Every token stops working.

## Back up and upgrade

The data volume holds the accounts, chats and settings. Back it up before every upgrade.

Back up the volume into a tar file in the current folder:

```bash theme={"dark"}
docker run --rm \
  -v open-webui-data:/data \
  -v "$PWD":/backup \
  alpine tar czf /backup/open-webui-data-$(date +%F).tgz -C /data .
```

Expected output: no output, and a file named `open-webui-data-<date>.tgz` in the current folder.

Pull the new tag, then recreate the container from it. Change `v0.13.4` to the tag you want:

```bash theme={"dark"}
docker pull ghcr.io/open-webui/open-webui:v0.13.4
docker rm -f open-webui
docker run -d --name open-webui \
  -p 3000:8080 \
  --env-file openwebui.env \
  -v open-webui-data:/app/backend/data \
  ghcr.io/open-webui/open-webui:v0.13.4
```

Check the health endpoint and sign in. Your accounts and chats should be unchanged. Then run the four checks in [Check the gateway path](https://www.truefoundry.com/docs/ai-gateway/open-webui/install-docker.md#check-the-gateway-path).

> [!NOTE]
>
> Open WebUI migrates its database on start-up. Read the release notes for the new tag before you upgrade, and keep the backup until you have checked a chat on the new version.

## Remove the install

Remove the container, the data volume and the env file. Removing the volume deletes every account and chat. Take a backup first if you need them.

```bash theme={"dark"}
docker rm -f open-webui
docker volume rm open-webui-data
rm -f openwebui.env
```

Expected output:

```text theme={"dark"}
open-webui
open-webui-data
```

Then delete the virtual account if you no longer need it, from **Access Management → Virtual Accounts**.

## Troubleshoot

| Symptom | Cause | Fix |
| - | - | - |
| `401` with `Invalid token` | The token was regenerated, copied with a missing character, or taken from the **EXPIRING SOON** row. | Copy the token from the **ACTIVE** row with **Get token**, rewrite `openwebui.env`, and recreate the container. |
| `403` with `not authorized to access model` | The model has no grant on this account. The model name may be bare. | Add the provider-qualified model in **Manage Permissions**. Use the full ID, such as `azure-openai-main/o4-mini`. |
| `400` with `not found in model account` | The bare name resolved to a provider that does not serve the model. | Use the provider-qualified ID. |
| `/health` returns `000` | The container is still starting, or it stopped. | Run `docker ps --filter name=open-webui`. Read the log with `docker logs open-webui`. |
| `port is already allocated` | Another process uses port 3000 on the host. | Stop it, or change the host side of `-p 3000:8080` and open that port. |
| Sign-up page still open | `ENABLE_SIGNUP=false` was not set, or the container was not recreated. | Add it to `openwebui.env` and recreate the container. |

## Checklist

* [ ] The virtual account has one granted model, and the grant uses the provider-qualified ID.
* [ ] The token was copied from the **ACTIVE** row, and `openwebui.env` is readable only by you.
* [ ] The container runs the pinned tag, and `/health` returns `200`.
* [ ] The models list returns `200`, the granted call returns `200`, and the ungranted call returns `403`.
* [ ] Public sign-up is off after the first admin is created.
* [ ] A backup exists before every upgrade.


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