OAuth2 Token Expiry Preflight and Refresh Prompt Template

This prompt is for integration engineers and platform teams who need an AI-assisted decision engine inside a retry harness. Use it when an API request fails with a 401 Unauthorized status and the error body indicates an expired access token. The prompt instructs the model to act as a credential-aware recovery agent: it validates the token expiry claim, selects the correct OAuth2 refresh grant flow, generates a secure token refresh request, and produces a replayed API call with the new credentials. This is not a general-purpose auth debugger. It assumes you already have a working OAuth2 client, stored refresh tokens, and a secure secret store. The prompt is designed to be embedded in middleware or a sidecar that intercepts 401 responses, not as a standalone chatbot.

The ideal user is an engineer wiring this prompt into an API gateway, a service mesh sidecar, or a retry middleware layer. The required context includes the original failed request (method, URL, headers, body), the full 401 error response (status code, headers, body), the current access token and its decoded claims, the stored refresh token, and the OAuth2 token endpoint configuration. Without this context, the model cannot validate whether the token is genuinely expired, cannot select the correct grant type, and cannot construct a valid refresh request. Do not use this prompt when the error is a 403 Forbidden (scope or permission issue), a 5xx server error, or a network timeout—those failures require different recovery strategies covered in sibling playbooks.

The prompt is designed for a single-step recovery decision, not a multi-turn conversation. It expects the harness to provide all necessary context in one request and to execute the model's output directly. The output is a structured decision object containing a refreshed access token, the replayed request with new Authorization headers, and metadata about the refresh operation. The harness must validate this output before replaying the request: check that the new token is non-empty and distinct from the expired one, verify that the replayed request preserves the original method, URL, and body, and confirm that the Authorization header has been updated. If the refresh token itself is expired or revoked, the model should signal an escalation to human-in-the-loop re-authentication rather than retrying indefinitely.

Before deploying this prompt, ensure your harness handles concurrent refresh safety. If multiple requests fail simultaneously with the same expired token, the harness must serialize refresh attempts or use an idempotency key to prevent multiple refresh calls that could invalidate the refresh token through rotation. The eval criteria for this prompt include: correct detection of token expiry from decoded claims, accurate selection of the refresh_token grant type, proper construction of the token endpoint request, and preservation of the original API call's intent and payload. Test against scenarios including already-refreshed tokens, revoked refresh tokens, and malformed error responses to ensure the model escalates appropriately rather than hallucinating a recovery.

The following prompt is designed to be injected into a retry harness immediately after an upstream API returns an HTTP 401 Unauthorized error. Its job is to act as a secure, credential-aware decision engine. It receives the failed request context, the current (expired) token metadata, and instructions for your secure secret store. It must never be asked to generate or store secrets itself; it only produces the sequence of steps your application code should execute. The prompt uses square-bracket placeholders for all dynamic values, which your harness must populate from the failed request object and a secure vault lookup before sending the prompt to the model.

textCopy
You are a credential-aware retry agent inside a secure application harness. Your task is to diagnose an OAuth2 token expiry failure and produce a safe, ordered recovery plan. You do not have direct access to secrets. You will instruct the harness to perform refresh and replay steps.

## Failure Context
- Failed Request Method: [HTTP_METHOD]
- Failed Request URL: [REQUEST_URL]
- Failed Request Headers (sanitized): [REQUEST_HEADERS]
- Failed Request Body (sanitized): [REQUEST_BODY]
- Upstream HTTP Status: [UPSTREAM_STATUS]
- Upstream Error Body: [UPSTREAM_ERROR_BODY]

## Current Token Metadata
- Token Type: [TOKEN_TYPE]
- Issued At (epoch): [ISSUED_AT]
- Expires At (epoch): [EXPIRES_AT]
- Token Scopes: [TOKEN_SCOPES]
- Refresh Token Exists: [REFRESH_TOKEN_EXISTS]
- Token Provider: [TOKEN_PROVIDER]

## Secure Store References (DO NOT EMIT VALUES)
- Client ID Reference: [CLIENT_ID_REF]
- Client Secret Reference: [CLIENT_SECRET_REF]
- Refresh Token Reference: [REFRESH_TOKEN_REF]
- Token Endpoint URL: [TOKEN_ENDPOINT_URL]

## Constraints
- [CONSTRAINTS]

## Output Schema
Produce a valid JSON object with the following structure:
{
  "decision": "refresh_and_replay" | "reauthenticate" | "escalate",
  "reasoning": "A concise explanation of the decision based on token metadata and error context.",
  "preflight_checks": [
    "Check 1: description and expected outcome",
    "Check 2: ..."
  ],
  "refresh_instruction": {
    "endpoint": "[TOKEN_ENDPOINT_URL]",
    "grant_type": "refresh_token",
    "client_id_ref": "[CLIENT_ID_REF]",
    "client_secret_ref": "[CLIENT_SECRET_REF]",
    "refresh_token_ref": "[REFRESH_TOKEN_REF]",
    "scope": "[TOKEN_SCOPES]"
  },
  "replay_instruction": {
    "method": "[HTTP_METHOD]",
    "url": "[REQUEST_URL]",
    "headers_to_replace": {
      "Authorization": "Bearer <NEW_ACCESS_TOKEN>"
    },
    "body": "[REQUEST_BODY]"
  },
  "concurrency_safety": {
    "idempotency_key": "[IDEMPOTENCY_KEY]",
    "refresh_token_rotation_handling": "Replace stored refresh token with new refresh token from response if present."
  },
  "escalation_reason": null
}

## Safety Rules
1. If the upstream error indicates an invalid_grant or invalid_client error during a hypothetical refresh, set decision to "escalate" and explain why.
2. If no refresh token exists, set decision to "reauthenticate" and instruct the harness to initiate a new authorization code flow.
3. Always include concurrency_safety instructions to prevent multiple parallel refresh attempts from invalidating a rotated refresh token.
4. Never output actual secret values. Use only the provided reference strings.

To adapt this template, start by replacing the [CONSTRAINTS] placeholder with your organization's specific retry policies. For example: "Maximum of 2 refresh attempts per request. If the token endpoint returns a 5xx error, retry with exponential backoff starting at 1 second, capped at 5 seconds. Do not replay the original request if the refreshed token has fewer scopes than the original." Next, ensure your harness validates the model's JSON output against the schema before executing any refresh or replay step. If the model produces an escalate decision, your harness must route the failure to a human-operable dead-letter queue or incident channel, attaching the full failure context and model reasoning. For high-security environments, add a pre-execution check that confirms the refresh_token_ref has not been used in another concurrent refresh since the prompt was generated. Finally, log every decision and its outcome to an audit trail that records the token provider, the decision type, and whether the replay ultimately succeeded, enabling future retry budget analysis and provider reliability tracking.

This prompt is designed to be called by a retry middleware layer, not directly by end-users. When an API request fails with a 401 Unauthorized status, the harness should catch the error, extract the original request context, and invoke this prompt to determine whether the token is expired, whether a refresh is possible, and how to replay the request safely. The prompt expects structured input including the error response headers, the current token's expiry claim (if decodable), the available grant types, and the original request method, URL, and body. The harness must never expose raw refresh tokens or client secrets to the model; instead, it should pass masked identifiers and let the application layer perform the actual credential rotation.

The implementation should follow a strict sequence: (1) Intercept the 401 response and extract the WWW-Authenticate header and any error codes. (2) Decode the current access token's exp claim without verification to get the expiry timestamp. (3) Assemble the prompt variables including [ERROR_CONTEXT], [TOKEN_METADATA], [GRANT_CONFIG], and [ORIGINAL_REQUEST]. (4) Call the model with temperature=0 and a JSON output schema to prevent creative interpretations. (5) Validate the model's output against a strict schema that requires a decision field (refresh, reauthenticate, or fail), a refresh_instruction object with grant type and parameter keys, and a replay_instruction object with the modified request. (6) If the decision is refresh, execute the token refresh using the application's secure credential store—never the model's output directly. (7) Replay the original request with the new token. (8) If the replay also fails with 401, increment a refresh counter and retry up to a configured maximum (default: 2 refreshes per request). Exceeding this limit must escalate to a human operator or a dead-letter queue, not loop indefinitely.

For concurrent request safety, the harness must implement a token refresh lock keyed on the client ID or session identifier. If multiple in-flight requests detect the same expired token, only one should perform the refresh while others await the new token. The prompt's [CONCURRENCY_CONTEXT] variable should indicate whether a refresh is already in progress. Log every preflight decision, refresh attempt, and replay outcome with correlation IDs that span the original request, the prompt evaluation, and the replayed request. This traceability is critical for debugging token rotation issues and for audit evidence in regulated environments. Avoid wiring this prompt into streaming response paths without first validating that the replay can resume from the correct offset without duplicating side effects.