Replace a provider key

A provider connection links your Millwork organization to a provider account. Replace its access on the same connection so you can keep its saved models. Millwork tests the replacement before switching. If the test fails, it keeps the previous settings; an expired or revoked credential still needs replacement before it can be used. For providers other than AWS Bedrock, remove the old API key only after the new access passes. A short-term Bedrock key or STS session keeps its existing AWS expiration; short-term Bedrock keys have no individual delete control. If a credential may be exposed, follow Data and credentials to revoke it promptly instead. Goal: Replace provider access while keeping the same connection and saved models. You are done when: the replacement passes its check and is in use on the same connection.

Replace access from your terminal

With the CLI installed and your Millwork key configured, find the connection:

millwork provider list

Use its connection ID:

millwork provider rotate "<connection ID from the list>"

Review the connection and saved models, then confirm replacement. OpenRouter asks you to approve access again; key-entry providers ask for a replacement key on the private setup page. For AWS Bedrock, renew access with the same method and source Region. Use a new Bedrock API key for an API-key connection; Millwork lists the account’s system profiles and requires the model already saved on that connection. For STS, use a fresh session with its actual expiration and the same exact inference-profile ARN. Renewal cannot switch methods. Return to the terminal. Millwork tests the new access before switching. Expected result: state is rotated: the CLI checked the replacement and switched to it. You keep the connection and saved models. For providers other than AWS Bedrock, remove the old API key in its controls after this check. A passing connection check confirms access; it does not submit a model task.

Continue an interrupted replacement

Keep the continuation command printed before setup starts. It includes the operation’s request key; the later command also includes --handoff-id. Run the printed command to continue the same replacement. It includes an npm form if millwork is not on your path. Do not generate another key to recover a response you did not receive. If the browser step expires, inspect the connection with millwork provider list before starting a fresh replacement. A failed or expired replacement keeps the old settings; it does not restore an expired or revoked credential.

Replace access from a script

Read the affected connection first:

millwork provider rotate "<connection ID>" --json

This returns action_required without changing the connection. After approval, use the returned command with --yes. That flag approves the credential operation only. It does not approve a paid run. A pending browser step returns exit code 2 with human_handoff, its action, expiry and continuation commands. JSON mode does not wait for the browser. Use --open-browser to request opening the current link; it cannot be combined with --no-browser. Complete the human step, then use the saved continuation with its original --idempotency-key and --handoff-id. Neither value is a provider key; keep actual keys and setup links out of chat.

Replace access through the REST API

Start a new browser setup for the existing connection. OpenRouter asks you to approve access again; a key-entry provider asks for a replacement key. AWS Bedrock keeps the connection’s existing method and asks for a new key or STS session for the same region and profile. Follow Provider setup fields for the details. Rotation does not start a paid run.

Before you begin

Set MILLWORK_API_URL and MILLWORK_API_KEY as shown in Make your first API call. Find the connection you are updating and the two values its secure setup needs:

curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  "$MILLWORK_API_URL/source-connections" |
jq '.connections[] | {connection_id, display_name, source_id, auth_scheme, status}'

Expected result: one line per connection. Keep the connection_id, source_id, and auth_scheme of the one whose access you are replacing.

Complete a new secure setup

Start a new secure setup, the one-time browser step, for the same connection. Use the connection’s existing source_id and auth_scheme.

umask 077
export CONNECTION_ID="<ID of the connection you are updating>"
ROTATION_REQUEST_KEY="provider-rotation-$(date +%s)"

if ! curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $ROTATION_REQUEST_KEY-setup" \
  --data '{ "source_id": "<the connection source_id>", "auth_scheme": "<the connection auth_scheme>" }' \
  --output handoff.json \
  "$MILLWORK_API_URL/source-credential-handoffs"; then
  echo "The request failed. Read handoff.json before continuing." >&2
  exit 1
fi

SETUP_ID="$(jq -er '.handoff_intent_id | strings | select(length > 0)' handoff.json)" || exit 1
jq -r '.continue_url' handoff.json

umask 077 keeps newly created response files private to you. Keep handoff.json out of source control and support messages. Keep ROTATION_REQUEST_KEY for this replacement. If a response is lost, replay that request with the same key and body after inspecting its saved state.Expected result: 201 with state pending, a handoff_intent_id, and a one-time continue_url. Open that link in a browser and replace access there: approve again for OpenRouter, enter the replacement for a key-entry provider, or renew AWS access with the same method, region and profile. Do not create a second connection. Then wait for setup to complete:

if ! curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  --output handoff-status.json \
  "$MILLWORK_API_URL/source-credential-handoffs/$SETUP_ID"; then
  echo "The status request failed. Inspect the same setup before continuing." >&2
  exit 1
fi

STATE="$(jq -er '.state' handoff-status.json)" || exit 1
if [ "$STATE" != "completed" ]; then
  echo "Setup state: $STATE. Follow the recovery below before switching." >&2
  exit 1
fi

Expected result: completed. If it is pending, finish the browser step and repeat this status read. If it is consumed, inspect the existing connection before taking another action. If it is expired or failed, start a new secure setup; the old link cannot be reused. The full request reference is in Connect a provider account.

Switch to the replacement access

if ! curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
    \"handoff_intent_id\": \"$SETUP_ID\"
  }" \
  --header "Idempotency-Key: $ROTATION_REQUEST_KEY-replace" \
  --output rotated-connection.json \
  "$MILLWORK_API_URL/source-connections/$CONNECTION_ID/rotate"; then
  echo "The replacement failed. Read rotated-connection.json before retrying." >&2
  exit 1
fi

jq '{
  status,
  test_state,
  binding_revision,
  tested_binding_revision,
  rotated_at
}' rotated-connection.json

Expected result: status is active, test_state is passed, and both revision numbers match. binding_revision identifies the current saved credential version; tested_binding_revision identifies the version that passed the connection test. Matching values confirm that Millwork tested the credentials now in use.

Finish replacing access

For providers other than AWS Bedrock, remove or revoke the old API key only after the new revision passes. Use the provider’s own controls. Millwork schedules deletion of its old saved credential; this is separate from revoking access at the provider. A short-term Bedrock key or STS session keeps its existing AWS expiration. Routine renewal does not require revoking the session or other keys.

If it fails

What happened	What to do
The replacement failed its test	Millwork keeps the previous connection settings. This does not restore an expired or revoked credential. Fix the replacement credentials, start a new secure setup, and switch again. Do not remove the old key at the provider yet.
The test reason is `authentication` or `permission`	Check the replacement access, expiration and required permissions. See Provider connection help.
The one-time setup link expired or was already used	Check the setup state. If it is `completed` or `consumed`, read `GET /v1/source-connections/{connectionId}` and check the connection’s status and revisions before repeating setup. Start a new setup only when the state is `expired` or `failed`.

Never send a provider key or a one-time setup URL to support.

Output checks

Agent workflows

Review jobs

Operations recipes

Replace a provider key

Replace access from your terminal

Continue an interrupted replacement

Replace access from a script

Replace access through the REST API

Before you begin

If it fails

​Replace access from your terminal

​Continue an interrupted replacement

​Replace access from a script

​Replace access through the REST API

​Before you begin

​If it fails

Replace access from your terminal

Continue an interrupted replacement

Replace access from a script

Replace access through the REST API

Before you begin

If it fails