Auth Monitoring

+15 Mana ✨
OpenClaw Auth Monitoring(DOCUMENTATION)OpenClaw Security Guide(DOCUMENTATION)

Introduction

OpenClaw agents depend on authentication credentials to access AI providers, external APIs, and chat platforms. When these credentials expire or become invalid, the agent silently stops working. Auth monitoring automates credential health checks, OAuth token expiry tracking, and proactive alerting so you are notified before credentials fail.

Key Concepts

  • Credential Health Check: A periodic verification that stored credentials are still valid and functional
  • OAuth Token Expiry Monitoring: Tracking the expiry time of OAuth tokens and alerting before they expire
  • Proactive Alerting: Notifying administrators days before credentials expire, rather than after failures occur
  • Token Refresh: The automatic renewal of expiring OAuth tokens using refresh tokens
  • Auth Profile: A named collection of credentials associated with a specific service or API

Real World Context

An agency manages OpenClaw agents for 15 clients. Each client has their own AI provider API keys, chat platform tokens, and OAuth credentials. Without auth monitoring, they only discover expired credentials when a client reports that their agent stopped responding. With auth monitoring, they receive alerts 7 days before any credential expires, giving them time to renew proactively.

Deep Dive

Credential Health Checks

Configure periodic validation of stored credentials:

json
{
  "auth": {
    "monitoring": {
      "enabled": true,
      "checkInterval": 3600,
      "profiles": [
        {
          "name": "anthropic-api",
          "type": "api-key",
          "validateEndpoint": "https://api.anthropic.com/v1/messages",
          "validateMethod": "HEAD"
        },
        {
          "name": "github-oauth",
          "type": "oauth2",
          "tokenEndpoint": "https://github.com/login/oauth/access_token"
        }
      ]
    }
  }
}

This configuration checks credentials every 3600 seconds (1 hour). The Anthropic API key is validated by making a HEAD request to the messages endpoint. The GitHub OAuth token is checked against the token endpoint. If either fails, an alert is generated.

OAuth Token Expiry Tracking

For OAuth credentials, monitor token expiry proactively:

json
{
  "auth": {
    "monitoring": {
      "oauth": {
        "alertBeforeExpiryDays": 7,
        "autoRefresh": true,
        "refreshRetries": 3,
        "refreshRetryDelaySeconds": 60
      }
    }
  }
}

This configuration alerts 7 days before any OAuth token expires. When auto-refresh is enabled, the system automatically uses the stored refresh token to obtain a new access token. If the refresh fails, it retries up to 3 times with a 60-second delay between attempts.

Alert Configuration

Configure where and how auth alerts are delivered:

json
{
  "auth": {
    "monitoring": {
      "alerts": {
        "channels": ["slack", "email"],
        "severity": {
          "expired": "critical",
          "expiringWithin7Days": "warning",
          "refreshFailed": "critical"
        },
        "recipients": {
          "slack": "#ops-alerts",
          "email": "ops-team@company.com"
        }
      }
    }
  }
}

Alerts are routed to Slack and email with severity levels based on the condition. Expired credentials and failed refresh attempts are critical. Credentials expiring within 7 days are warnings. Recipients are configured per channel.

Monitoring Dashboard Data

Auth monitoring exposes data for dashboards:

bash
openclaw auth status

This command shows all auth profiles with their current status, last validation time, token expiry dates, and any active alerts. It provides a single-pane view of your credential health across all configured services.

Common Pitfalls

  • Not monitoring OAuth refresh token expiry: Access tokens expire frequently, but refresh tokens also expire (typically after 90 days). Monitor both.
  • Setting checkInterval too high: Checking credentials once a day means you could have up to 24 hours of downtime before detecting an expired credential.
  • Relying solely on auto-refresh: Auto-refresh can fail if the refresh token itself has expired or been revoked. Always configure alerts as a backup.

Best Practices

  • Set alertBeforeExpiryDays to at least 7 to give yourself time to renew credentials before they expire.
  • Enable auto-refresh with retries for OAuth tokens to handle transient failures automatically.
  • Route critical alerts to multiple channels to ensure they are not missed.

Summary

  • Auth monitoring automates credential health checks and OAuth token expiry tracking
  • Configure periodic validation of API keys and OAuth tokens against their respective endpoints
  • Proactive alerting notifies you days before credentials expire, preventing silent failures
  • Auto-refresh with retries handles OAuth token renewal automatically
  • Use openclaw auth status for a comprehensive view of credential health
✓ Completed