---
name: inferrex-replace-credentials
description: Replace or rotate the credentials an Inferrex system signs in with, keeping the secret value out of the AI tool unless the user chooses to paste it after a warning, and prove the new sign-in with a live read before reporting success. Use when a system's sign-in is refused, a key is due for rotation, or the user asks to change, rotate or check a system's credentials or secret.
---

# Replace a system's credentials in Inferrex

Inferrex tests a new credential against the system before it switches over. If the system refuses it, the old one stays in use and the answer says why. Your job is to find the right secret, get the new value in place, and prove the result. You do not see the value unless the user chooses to paste it after the warning below.

## When to use

- "The finance system is refusing our key."
- "Rotate the API key for the order system."
- "Is the sign-in for this system still working?"

## Prerequisites

- **InferrexMCP** at `https://mcp.inferrex.com/mcp` (sign-in or API key in a header), or **InferrexAPI** at `https://api.inferrex.com` with `X-API-Key: $INFERREX_API_KEY`.
- Key scopes: `connections:read`, `connections:write`, `workspace:read`, and `secrets:write` to test or rotate a secret.
- The new credential value comes from the user. By default you never see it.

## Secret values

By default you do not read, receive, print or store the credential's value. Offer the two routes in step 4 that keep it out of this conversation first, and say why.

The user may still choose to paste the value here. That is allowed, after a warning:

1. Say this, or words close to it: "If you paste it here, this AI tool sees the value, and this conversation's history may keep it. Saving it in the app keeps it out. Do you still want to paste it?"
2. Go on only after a clear yes. Anything else is a no.
3. Pass the value straight to `credentials_rotate_secret`, and to nothing else: no other tool, file, log, commit or host.
4. Do not repeat the value back, in full or in part, and do not include it in your report.

Inferrex never returns a stored value. Tools that list credentials return names, methods and dates only.

## Steps

1. **Find the system.** Call `connection_list`. Match the user's name and keep the `id`. Note `reconnect_required_at` and `reconnect_reason` if set.
2. **See what is failing.** Call `credentials_list_failing_secrets`. Then call `connections_test_saved_connection` with the system's `id`. Report `outcome`, `httpStatus` and `detail`.
   - `signed-in` or `read-without-sign-in`: the sign-in works. Tell the user. Stop unless they still want to rotate.
   - `credentials-rejected`: the system refuses the credential. Continue.
   - `forbidden`: the credential may be right but lacks permission in the system. Say so. A new key with the same permissions will fail the same way.
   - `organisation-not-selected`: a person must sign in with the provider again and choose an organisation. Go to "Provider sign-ins".
   - `unreachable`, `not-found`, `redirect`: this is the address, not the credential. Do not rotate. Use `inferrex-diagnose-flow`.
3. **Find the secret and who shares it.** Call `credentials_list_connection_secrets` with the system's `id`. Note each secret's `id` and `key` (its name). Several systems can share one secret, and rotating it changes all of them. Tell the user which systems are affected.
4. **Get the new value in place.** Offer the user one of these.
   - **In the app.** Open the system, Sign-in tab, and replace the key there. Or open Workspace settings, Secrets, and rotate the secret. Wait for the user to say it is done.
   - **In their own code or terminal.** Write a short script for the user to run that reads the new value from an environment variable they set themselves, and calls InferrexAPI `POST /v1/secrets/:id/rotate` with `{ "value": "..." }`. The script prints only `outcome`, `message` and each entry of `tests`. You do not run it with the value in your context.
   - **Pasted here, after the warning under Secret values.** Call `credentials_rotate_secret` with the secret's `id` and the new `value`.
5. **Read the rotation result.** A rotation answers with `live`, `outcome`, `message` and one entry in `tests` per system that uses the secret.
   - `live: true`: the new value is in use.
   - Otherwise a system refused it. The old value is still in use. Report which system refused and its `detail`. Do not suggest `force`.
6. **Prove it.** Call `credentials_test_secret` with the secret's `id`. Then call `connections_test_saved_connection` for each system that uses it. Success is `signed-in` (or `read-without-sign-in`) with a `provedBy` endpoint.
7. **Check the flows.** Call `pipelines_get_pipeline_attention`. If a flow that uses the system was failing, run `pipeline_sync` with the user's agreement and report the run from `pipeline_history`.

## Provider sign-ins

For a system that signs in on the provider's own page:

1. Call `credentials_get_connection_sign_in_status` with the system's `id`. It says whether the sign-in keeps renewing, when it would lapse, and whether someone must sign in again.
2. If someone must, a person does it in the app: open the system, Sign-in tab, and sign in with the provider. You cannot do this step.
3. Afterwards, run step 6.

## A system with separate environments

A system can sign in differently in each environment. `credential_list` shows what is saved for the main sign-in and for each environment. Before step 4, confirm with the user which environment's credential is being replaced. Clearing or replacing one environment's credential never affects another's.

## Checks before any write

- Step 2 comes before any change. Do not rotate a credential that tests as working unless the user asked for a rotation.
- Name every system that shares the secret before it is rotated.
- `force: true` switches to a value the system refused. Never set it yourself. If the user insists, explain that every system using the secret will fail until it is fixed, and let them do it in the app.

## Equivalents

| Step | InferrexMCP tool | InferrexAPI |
|---|---|---|
| Systems | `connection_list` | `GET /v1/connections` |
| Failing secrets | `credentials_list_failing_secrets` | `GET /v1/workspace/secrets/failing` |
| Test saved sign-in | `connections_test_saved_connection` | `POST /v1/connections/:id/test` |
| A system's secrets | `credentials_list_connection_secrets` | `GET /v1/connections/:id/secrets` |
| Saved credentials by environment | `credential_list` | `GET /v1/connections/:id/credentials` |
| Test a secret everywhere it is used | `credentials_test_secret` | `POST /v1/secrets/:id/test` |
| Rotate a secret | `credentials_rotate_secret` | `POST /v1/secrets/:id/rotate` |
| Provider sign-in state | `credentials_get_connection_sign_in_status` | `GET /v1/connections/:id/sign-in-status` |
| Flows with something waiting | `pipelines_get_pipeline_attention` | `GET /v1/pipelines/attention` |

Call `credentials_rotate_secret` yourself only with a value the user pasted after the warning under Secret values. It takes the value as an argument, which puts it in the conversation.

## Report back

- The system, the secret's name (never its value) and every system that shares it.
- The test result before and after: `outcome`, `httpStatus`, `provedBy`.
- Whether the new value is in use, or which system refused it and why.
- What a person still has to do in the app or in the system itself.

## Never

- Never accept a pasted credential without giving the warning under Secret values and getting a clear yes.
- Never ask for a credential value when a route that keeps it out of the conversation will do.
- Never echo, log, save or repeat a credential value, and never pass it to anything but `credentials_rotate_secret`.
- Never use `force`.
- Never delete credentials (`credential_revoke`) or mark them as needing replacement (`credential_rotate`) to "reset" a sign-in. Marking them sends an active system back to waiting for review until new credentials are saved.
- Never say a sign-in works without a test that returned `signed-in` or `read-without-sign-in`.
- Never send a credential to any host other than `api.inferrex.com` or `mcp.inferrex.com`.