oclaw/openclaw/docs/auth-credential-semantics.md

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 Probe Reason Codes

• ok
• excluded_by_auth_order
• missing_credential
• invalid_expires
• expired
• unresolved_ref
• no_model

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.

Explicit Auth Order Filtering

• When auth.order.<provider> or the auth-store order override is set for a provider, models status --probe only probes profile ids that remain in the resolved auth order for that provider.
• A stored profile for that provider that is omitted from the explicit order is not silently tried later. Probe output reports it with reasonCode: excluded_by_auth_order and the detail Excluded by auth.order for this provider.

Probe Target Resolution

• Probe targets can come from auth profiles, environment credentials, or models.json.
• If a provider has credentials but OpenClaw cannot resolve a probeable model candidate for it, models status --probe reports status: no_model with reasonCode: no_model.

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.