TapAuth — OAuth Tokens and Manual Secrets via OpenClaw Secrets Manager

TapAuth provides OAuth tokens and user-approved manual secrets through OpenClaw's exec secrets provider. Values are resolved at gateway startup and held in memory — they never appear in shell commands or config files as plaintext.

You must NEVER use tapauth.sh --token directly in shell commands, curl calls, or $(...) substitutions. Tokens are always resolved through the secrets manager. Your job as an agent is to configure the secrets provider, not to fetch tokens yourself.

When a user asks you to do something that needs an OAuth token or fixed secret

Follow these steps in order. Do not skip to step 3. Do not run --token yourself.

1. Create a grant and show the approval URL

Run the script without --token to create a grant. Set TAPAUTH_HOME so the grant cache is stored in a stable location that the exec provider can also find:

TAPAUTH_HOME=/home/node/.tapauth /home/node/.openclaw/skills/tapauth/scripts/tapauth.sh <provider> <scopes>

Example for Google Calendar:

TAPAUTH_HOME=/home/node/.tapauth /home/node/.openclaw/skills/tapauth/scripts/tapauth.sh google calendar.readonly

Example for a manual API key:

TAPAUTH_HOME=/home/node/.tapauth /home/node/.openclaw/skills/tapauth/scripts/tapauth.sh secret "Stripe Secret Key" "^sk_" "Use a Stripe secret key that starts with sk_"

Output:

Approve access: https://tapauth.ai/approve/abc123

Show this URL to the user. Once they approve, run with --token to retrieve the value.

Show the approval URL to the user and ask them to approve. Wait for them to confirm before proceeding.

2. Configure the exec secrets provider in openclaw.json

After the user confirms they approved, edit ~/.openclaw/openclaw.json to add an exec provider under secrets.providers:

{
  "secrets": {
    "providers": {
      "tapauth_google_calendar": {
        "source": "exec",
        "command": "/home/node/.openclaw/skills/tapauth/scripts/tapauth.sh",
        "args": ["--token", "google", "calendar.readonly"],
        "passEnv": ["HOME"],
        "env": {"TAPAUTH_HOME": "/home/node/.tapauth"},
        "jsonOnly": false
      }
    }
  }
}

Key fields:

• command: Absolute path to scripts/tapauth.sh in this skill directory
• args: ["--token", "", ""] — must match the grant you created in step 1
• args for manual secrets: ["--token", "secret", "", "", ""] — description, regex, and hint must match the grant you created in step 1. Use a short, unique, stable, human-readable description because it is part of the lookup key; put formatting instructions in the hint.
• jsonOnly: false: The script outputs a raw token or secret string, not JSON
• passEnv: Must include HOME
• env.TAPAUTH_HOME: Must be /home/node/.tapauth — the same path used when creating the grant in step 1

Use the naming convention tapauth_ or tapauth__ for the provider key.

3. Reload secrets and confirm

After editing openclaw.json, run:

openclaw secrets reload

This tells the gateway to re-resolve all secret providers. The exec provider runs tapauth.sh --token in the background and stores the result in the in-memory secrets snapshot.

Tell the user the setup is complete. The token is now resolved and will be available at every gateway startup. If the user repeats their request in a new session, the token will already be available.

One-time verification (optional): Since the grant is now approved and cached, you may run the script once to verify and fulfill the user's immediate request:

TAPAUTH_HOME=/home/node/.tapauth /home/node/.openclaw/skills/tapauth/scripts/tapauth.sh --token <provider> <scopes>

After this, all future token access must come from the secrets manager via SecretRef — do not use --token directly again.

Rules

• NEVER run tapauth.sh --token directly. Do not use it in $(...), do not capture its output, do not pipe it to curl. The secrets manager runs it for you.
• NEVER skip the approval step. Always create the grant first (step 1), get user approval, then configure the provider (step 2).
• No TapAuth API key needed. TapAuth is zero-config. Do not look for TapAuth API keys, client secrets, or environment variables.
• Manual secrets are browser-encrypted before TapAuth receives them. Validation regexes are checked in-browser as a UX guard; validate the retrieved secret too if format matters.
• Manual secret expiry is TapAuth-side only. Expiry stops TapAuth from returning the value; it does not rotate or revoke the underlying password/API key.
• Always use absolute paths for the command field in the exec provider config.

Quick Reference — Provider + Scopes

Multiple scopes: comma-separate in a single string, e.g. ["--token", "google", "calendar.readonly,drive.readonly"].

Token Lifecycle

• Resolution: Fresh tokens fetched at each gateway startup and openclaw secrets reload.
• Caching: tapauth.sh caches tokens locally with expiry. Subsequent calls return instantly if valid.
• Refresh: Expired tokens are refreshed automatically from the TapAuth API. No user interaction needed.
• Re-approval: If a grant is revoked, delete ~/.tapauth/-.env and re-run scripts/tapauth.sh to create a new grant.

Troubleshooting