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

# Rotate credentials

> Rotate Virtual Account tokens, Personal Access Tokens, MCP server credentials, gateway installation tokens, and SCIM tokens without breaking the applications that use them.

This guide covers rotating each type of credential on the TrueFoundry platform without breaking the applications that use it.

| Credential | Where | Grace period? |
| - | - | - |
| Virtual Account token | **Access Management → API Keys → Virtual Accounts** → active token button → **Regenerate token** | Yes — you choose it; keep it short |
| Personal Access Token | **Settings → Organisation → Revoke all PAT** | No — immediate, and applies to all users |
| MCP API key | **MCP Gateway →** server → **Edit → Auth Data →** Headers value | No — create new, update, then invalidate old |
| MCP OAuth2 | **MCP Gateway →** server → **Edit → Auth Data →** Client ID / Secret | No — create new, update, then invalidate old |
| Gateway installation token | **Settings → Gateway Endpoints** — create new, cut over, delete old, fix URL | No — cut over the running gateway before deleting the old installation |
| SCIM token | **Settings → Security & Access → Provisioning →** SCIM **View Config → Regenerate token** | Yes — previous token stays valid until its expiry period ends |

## Virtual Account tokens

Virtual Accounts are the API keys your applications use. Rotation is zero-downtime: the new token is issued immediately, and the old one stays valid for a grace period you choose.

For scheduled rotation, notifications, and syncing tokens to a secret store, see [Manage Virtual Accounts](https://www.truefoundry.com/docs/platform/virtual-account-management.md#retrieve-and-rotate-tokens).

**1. Open the Virtual Accounts list**

Go to **Access Management → API Keys → Virtual Accounts**. Find your account and confirm the owner shown under **NAME & OWNER** matches the team that owns the application. The **EXPIRES/ROTATES AT** and **LAST ACCESSED** columns tell you when the current token expires and whether the application is still using it.

![Virtual Accounts list showing name and owner, permissions summary, expiry and last accessed time](https://mintcdn.com/truefoundry/KST5UEZ_KIzKaVQo/images/docs/platform/virtual-accounts-list.png?fit=max\&auto=format\&n=KST5UEZ_KIzKaVQo\&q=85\&s=32465d15bc3cf66c2d13af2b5585d7be)

Virtual Accounts list

**2. Open the account's tokens and regenerate**

In the **MANAGE TOKENS** column, click the active token button on your account's row (for example, **1 active token**). This opens the **Manage tokens** dialog, which lists every token issued for that Virtual Account with its expiry and last use.

In the **Manage tokens** dialog, click **Regenerate token** at the top right.

![Manage Tokens dialog listing token ID, creation time, expiry and last used, with Get Token and Regenerate Token actions](https://mintcdn.com/truefoundry/KST5UEZ_KIzKaVQo/images/docs/platform/virtual-account-tokens.png?fit=max\&auto=format\&n=KST5UEZ_KIzKaVQo\&q=85\&s=3b714eeae99912f0a4036b4010f28557)

Manage tokens dialog

**3. Choose the grace period**

The dialog asks for a **Grace Period**. This is your window to swap the token in everywhere it is used:

* A new token is created immediately.
* The old token keeps working for the full grace period.
* When the grace period expires, the old token is invalidated.

Keep this as short as you safely can — 15 or 30 minutes is usually right — so the old token is retired quickly. Do not go below the time you actually need to update the application.

> [!WARNING]
>
> Be careful with this choice. Pick a period you are confident you can finish inside. Too short and the old token is invalidated mid-swap, and the application starts failing authentication. Too long and a retired token stays valid longer than it should.

| Your situation | Suggested grace period |
| - | - |
| You can redeploy the application yourself, right now | 15–30 minutes |
| Token lives in a secret store or CI variable you control | 30–60 minutes |
| You depend on another team to deploy the change | A few hours, agreed with them in advance |
| Token is used by multiple services | The shortest window every owner confirms they can meet |

**4. Swap it in and verify**

Back in the **Manage tokens** dialog, click **Get token** next to the new token to copy it. Put it in your secret manager (never into a ticket or chat), redeploy the consuming services, then confirm traffic has moved over via the **LAST ACCESSED** column — before the grace period expires.

## Personal Access Tokens

PATs are per-user credentials.

### For individual users

Revocation is immediate — every existing PAT stops working the moment the admin clicks **Revoke all PAT**. Each user then generates a new token under **Access → Personal Access Tokens** and uses that one from then on.

To revoke PATs for a single user instead of the whole tenant, use **Revoke All PATs** on that user from **Access → Users**. See [User management](https://www.truefoundry.com/docs/platform/user-management.md#suspending-access).

### For scripts, CLI sessions, and integrations

Any script, CLI session, or integration authenticating with a PAT will fail until its token is updated. Plan this outside business hours as much as possible.

**1. Open Revoke all PAT**

Go to **Settings → Organisation → Account Management → Revoke all PAT**.

**2. Revoke every PAT**

Click the **Revoke all PAT** button. This deletes tokens for every user immediately and cannot be undone.

![Revoke all PAT section under Account Management settings](https://mintcdn.com/truefoundry/r66kE_72pIvLrrCy/images/revoke-all-pats.png?fit=max\&auto=format\&n=r66kE_72pIvLrrCy\&q=85\&s=e6492444eec7b00291dd4a64caa73016)

Revoke all PAT in Account Management

**3. Issue new tokens**

Each user creates a new PAT under **Access → Personal Access Tokens** and updates any script, CLI session, or integration that still held the old value. See [API Keys](https://www.truefoundry.com/docs/generating-truefoundry-api-keys.md#personal-access-tokens-pats).

> [!TIP]
>
> Production workloads should use Virtual Account tokens with auto-rotation, not PATs. See [Security settings](https://www.truefoundry.com/docs/platform/security-settings.md#recommended-configuration).

## MCP Server credentials

MCP server credentials have no grace period, so rotation is a three-step process: create the new credential at your provider, update it in TrueFoundry, then invalidate the old one.

For auth architecture and revoking every stored token on a server at once, see [MCP Gateway authentication and security](https://www.truefoundry.com/docs/ai-gateway/mcp/mcp-gateway-auth-security.md).

**1. Generate a new credential at your provider**

This depends on the MCP server. Go to the provider that issues the credential and create a new one — an OAuth2 client credential or a direct API key / token, whichever that server uses. Leave the old credential active for now so nothing breaks before the next step.

**2. Update the credential in TrueFoundry**

Open **MCP Gateway → MCP Registry**, click **⋮** on the server → **Edit**, and go to **Auth Data**. Then follow whichever section below matches your auth type.

> [tab] API Key
>
> With **API Key** selected, replace the value in the **Headers** row (for example, the `Authorization` header). The header name stays the same; only the value changes.
>
> ![MCP server Auth Data form with API Key selected and a shared Authorization header value](https://mintcdn.com/truefoundry/yR_clVDeJDlQkXKY/images/docs/ai-gateway/add-mcp-server-api-key-shared.png?fit=max\&auto=format\&n=yR_clVDeJDlQkXKY\&q=85\&s=bdd8c03ce7241753703264147b1e6f41)
>
> API Key auth with a shared header value
>
> If the server uses **Individual Credentials**, the header holds a placeholder such as `Bearer {{API_KEY}}` and each user updates their own key instead — no change is needed here. See [Auth Overrides](https://www.truefoundry.com/docs/ai-gateway/mcp/mcp-server-auth-overrides.md).

> [tab] OAuth2
>
> With **OAuth2** selected, update the **Client ID** and **Client Secret** fields with the new values. Leave the **OAuth Provider**, **Grant Type**, and **Token URL** unchanged unless those have also moved.
>
> ![MCP server Auth Data form with OAuth2 fields including Client ID and Client Secret](https://mintcdn.com/truefoundry/yR_clVDeJDlQkXKY/images/docs/ai-gateway/mcp-server-oauth2-config.png?fit=max\&auto=format\&n=yR_clVDeJDlQkXKY\&q=85\&s=e810314f881eb955da194e66e8fde5d9)
>
> OAuth2 client credentials on an MCP server

Save the server, then re-run a request through it to confirm the new credentials authenticate. Users on an Authorization Code flow may need to sign in again.

**3. Invalidate the old credential at your provider**

Once the new credential is confirmed working, go back to your provider and revoke or delete the old token / OAuth credential so it can no longer be used.

## Gateway installation tokens

The gateway installation token (`GatewayToken`) is how a self-hosted AI Gateway authenticates to the TrueFoundry control plane. Tokens are bound to a gateway installation entry — there is no regenerate action — so rotation means creating a new installation, cutting the running gateway over to its token, deleting the old installation, and restoring the real URL on the new one.

You create the new entry with a temporary example URL because the real gateway URL is still attached to the old installation. After the old entry is deleted, you edit the new entry and set the real URL.

For the create and token APIs used at first install, see [Deploy Gateway Plane](https://www.truefoundry.com/docs/platform/deploy-gateway-plane.md).

**1. Note the current installation**

Go to **Settings → Gateway Endpoints**. Record the existing installation's **name** and **URL** (for example, `https://gateway.example.com`). You need the URL again when you fix the new entry at the end.

**2. Create a new gateway installation with an example URL**

Create a second gateway endpoint with a unique name. Use a temporary example URL that is not already taken — for example, `https://gateway-rotate-temp.example.com` — so the create succeeds while the real URL still belongs to the old installation.

![Create Gateway Endpoint form with name and URL fields](https://mintcdn.com/truefoundry/lnxIRrswCNYXyDiZ/images/gateway-endpoint-form.png?fit=max\&auto=format\&n=lnxIRrswCNYXyDiZ\&q=85\&s=f69495b052adc9402c96bbe861dfedc8)

Create Gateway Endpoint

Or via the API:

```bash theme={"dark"}
curl -X 'PUT' --location 'https://<CONTROL_PLANE_URL>/api/svc/v1/llm-gateway/installations' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PERSONAL_ACCESS_TOKEN>' \
  -d '{
    "manifest": {
      "type": "gateway-installation",
      "name": "<NEW_GATEWAY_INSTALLATION_NAME>",
      "url": "https://gateway-rotate-temp.example.com",
      "enabled": true,
      "isDefault": false
    }
  }'
```

**3. Generate the new GatewayToken and cut over the running gateway**

Generate a token for the **new** installation name:

```bash theme={"dark"}
curl --location 'https://<CONTROL_PLANE_URL>/api/svc/v1/llm-gateway/installations/token?name=<NEW_GATEWAY_INSTALLATION_NAME>' \
  --header 'Authorization: Bearer <PERSONAL_ACCESS_TOKEN>'
```

Copy the new `GatewayToken`, store it securely, then update the Kubernetes secret the gateway reads (typically `TFY_API_KEY` on `truefoundry-creds`) and restart the gateway so it authenticates with the new token. Confirm the gateway is healthy against the control plane before continuing.

> [!WARNING]
>
> Do not delete the old installation until the running gateway is using the new token. Deleting first disconnects the gateway immediately.

**4. Delete the old gateway installation**

In **Settings → Gateway Endpoints**, delete the previous installation. That frees the real gateway URL so the new entry can take it.

**5. Fix the URL on the new installation**

Edit the new gateway endpoint and replace the temporary example URL with the real URL you recorded in step 1 (for example, `https://gateway.example.com`). Save, then confirm clients still reach the gateway at that URL and that the gateway remains connected to the control plane.

Via the API, send the full manifest including `isDefault`:

```bash theme={"dark"}
curl -X 'PUT' --location 'https://<CONTROL_PLANE_URL>/api/svc/v1/llm-gateway/installations' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PERSONAL_ACCESS_TOKEN>' \
  -d '{
    "manifest": {
      "type": "gateway-installation",
      "name": "<NEW_GATEWAY_INSTALLATION_NAME>",
      "url": "https://gateway.example.com",
      "enabled": true,
      "isDefault": true
    }
  }'
```

## SCIM tokens

The SCIM bearer token is what your identity provider uses to call TrueFoundry's SCIM API for user and team provisioning. Rotation issues a new token immediately; the previous token stays valid until its expiry period ends, so you can update the IdP before provisioning breaks.

For first-time SCIM setup, see [SCIM provisioning](https://www.truefoundry.com/docs/platform/sso/overview.md#scim-provisioning-at-a-glance) and the IdP-specific guides under [SSO](https://www.truefoundry.com/docs/platform/sso/overview.md).

**1. Open SCIM configuration**

Go to **Settings → Security & Access → Provisioning**. On the **SCIM** row, click **View Config**.

![Provisioning settings with SCIM enabled and View Config button](https://mintcdn.com/truefoundry/SXJFj4sAu_qDlAK4/images/settings-provisioning-scim-view-config.png?fit=max\&auto=format\&n=SXJFj4sAu_qDlAK4\&q=85\&s=14fe299e910a51737c03b3f41eb82d3a)

SCIM on the Provisioning page

**2. Regenerate the token**

In the **SCIM configuration** dialog, click **Regenerate token**. Copy the new **Token**, or click **Download** to save the credentials. Treat it like a password.

![SCIM configuration dialog with Regenerate token and Download](https://mintcdn.com/truefoundry/SXJFj4sAu_qDlAK4/images/settings-provisioning-scim-config.png?fit=max\&auto=format\&n=SXJFj4sAu_qDlAK4\&q=85\&s=30782ddebc405fdaa1013a7d72761ff9)

SCIM configuration with Regenerate token

> [!WARNING]
>
> The previous token stays valid only until its expiry period ends. Update your IdP with the new bearer token before then, or SCIM provisioning will start failing with `401` responses.

**3. Update the bearer token in your IdP**

In your identity provider's SCIM / provisioning settings, replace the **Bearer Token** / **Secret Token** / **API Token** with the new value from TrueFoundry. Leave the SCIM Base URL unchanged unless it has also moved.

Then test the connector or trigger a provisioning sync. Confirm users and groups still sync into TrueFoundry.

## Anything not covered here

This guide covers Virtual Account tokens, Personal Access Tokens, MCP server credentials, gateway installation tokens, and SCIM tokens. For anything else — other settings, edge cases, or a step that does not match what you see — follow the rest of the [TrueFoundry docs](https://www.truefoundry.com/docs/platform/overview.md), or contact **[security@truefoundry.com](mailto:security@truefoundry.com)** and we will help you through it.


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