## TL;DR
Refresh or replace the run credential and make the agent recover from expiry instead of dying on it. Confirm the credential lifetime and where the agent stores it, issue a fresh credential with a lifetime that covers the longest run, add a refresh-or-retry-once behaviour on a 401 with a state check before repeating the interrupted step, and resume the run from its checkpoint.

```text
auth token expired: agent failed with error 401 unauthorized
```

## Use this when
- The agent completes early provisioning steps, then calls start returning 401 during create the new hire Okta account.
- Runs that finish quickly succeed while long or bulk runs fail partway.
- The credential was issued hours before the run or is shared with another job that rotated it.

## Not for this skill when
- Every call returns 401 from the start. That is a wrong or revoked credential, handled as a connection repair.
- The 401 names a specific user permission rather than the caller. Fix the target authorization for that operation.

## Steps
1. Correlate the first 401 in the run log with the credential issue time and lifetime: check when the credential the agent uses was created or last refreshed and the expiry its issuer states, confirming the run simply outlived it. Verify: issue time, lifetime, and first-401 time line up as the expiry explanation
2. Check for competing rotation: confirm no other job, admin, or rotation policy replaced the credential mid-run, because a shared credential rotated elsewhere produces the identical symptom with a different owner. Verify: competing rotation is confirmed or ruled out from the issuer audit log
3. Issue a fresh credential for the agent through the approved store, with a lifetime and refresh arrangement suited to automation, and update the agent secret reference without copying the value into the run configuration or tickets. Verify: the agent reads the new credential reference and a single test call succeeds
4. Add expiry handling to the agent: on a 401, refresh or reload the credential once, verify the interrupted step state in the target before repeating it, and only then continue; a second 401 stops the run with a clear credential alert. Verify: a forced-expiry test shows the recover-once behaviour working
5. Resume the run from its checkpoint for the remaining hires and confirm the create the new hire Okta account step completes for each, with no duplicates from the interrupted step. Verify: the resumed run completes and target states are correct
6. Set an expiry early-warning: track the credential end date in the team inventory with a reminder before it lapses, and prefer refresh-capable authorization for long-running agents wherever the target supports it. Verify: the reminder exists with a named owner

## Why it happens
Agent runs are long-lived compared with interactive calls, so a credential that was valid at start can expire mid-run, and every later call fails identically with 401 even though nothing about the data or permissions changed. Shared credentials add a second clock, someone else rotation, that produces the same cliff. The failure looks like a permissions problem and invites wasted investigation unless the timeline is checked first. Refresh-aware agents and tracked lifetimes turn expiry from a run-killer into a routine, self-healing event.

## Variants and edge cases
### Short-lived credentials by policy
Where policy caps lifetimes below run duration, the agent must acquire a fresh credential per hire batch by design, using the approved issuance flow each time.

### Clock skew makes valid credentials look expired
If 401s appear immediately on fresh credentials, check the agent host clock against the issuer, since skew invalidates otherwise good credentials.

### Refresh works but the run still stops
Some frameworks cache the credential at run start. Configure the tool layer to reload on a 401 rather than only the agent top level.

Compatibility: Applies to agent provisioning runs using the Okta API with expiring credentials. Requires credential store and agent configuration access.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_RQl6z2UDQBSQ1UZsKuZHqg