openclaw/docs/auth-credential-semantics.md

title, summary, read_when

title	summary	read_when
Auth Credential Semantics	Canonical credential eligibility and resolution semantics for auth profiles	Working on auth profile resolution or credential routing Debugging model auth failures or profile order

Auth Credential Semantics

This document defines the canonical credential eligibility and resolution semantics used across:

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status --probe
• doctor-auth

The goal is to keep selection-time and runtime behavior aligned.

Stable Reason Codes

• ok
• missing_credential
• invalid_expires
• expired
• unresolved_ref

Token Credentials

Token credentials (type: "token") support inline token and/or tokenRef.

Eligibility rules

1. A token profile is ineligible when both token and tokenRef are absent.
2. expires is optional.
3. If expires is present, it must be a finite number greater than 0.
4. If expires is invalid (NaN, 0, negative, non-finite, or wrong type), the profile is ineligible with invalid_expires.
5. If expires is in the past, the profile is ineligible with expired.
6. tokenRef does not bypass expires validation.

Resolution rules

1. Resolver semantics match eligibility semantics for expires.
2. For eligible profiles, token material may be resolved from inline value or tokenRef.
3. Unresolvable refs produce unresolved_ref in models status --probe output.

OAuth SecretRef Policy Guard

• SecretRef input is for static credentials only.
• If a profile credential is type: "oauth", SecretRef objects are not supported for that profile credential material.
• If auth.profiles.<id>.mode is "oauth", SecretRef-backed keyRef/tokenRef input for that profile is rejected.
• Violations are hard failures in startup/reload auth resolution paths.

Legacy-Compatible Messaging

For script compatibility, probe errors keep this first line unchanged:

Auth profile credentials are missing or expired.

Human-friendly detail and stable reason codes may be added on subsequent lines.