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, then start --token immediately; it waits until approval completes.

Show the approval URL to the user, then proceed immediately. Do not ask the user to reply "done." The exec secrets provider will run tapauth.sh --token and wait while the user approves in the browser.

2. Configure the exec secrets provider in openclaw.json

Immediately after sharing the approval URL, 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", "<provider>", "<scopes>"] — must match the grant you created in step 1
• args for manual secrets: ["--token", "secret", "<description>", "<validation_regex>", "<validation_hint>"] — 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_<provider> or tapauth_<provider>_<scope> for the provider key.

Add a matching SecretRef wherever the OpenClaw config field accepts secrets for the user's task. The SecretRef must use the provider key above and id: "value".

3. Reload secrets while the user approves

After editing openclaw.json, run:

openclaw secrets reload

This tells the gateway to re-resolve referenced secrets. When a SecretRef points at the TapAuth provider, the exec provider runs tapauth.sh --token in the background and stores the result in the in-memory secrets snapshot.

Run this immediately after sending the approval URL. If approval is still pending, the command waits up to 10 minutes; keep the process running or track it as a background command. Once it completes, fulfill the user's original request without requiring a separate confirmation message.

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 wait for a "done" reply before configuring OpenClaw. Always create the grant first (step 1), show the URL, configure the provider, then let openclaw secrets reload poll while the user approves.
• 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 grant credentials locally. Bearer tokens and approved secrets are fetched on demand and are not written to disk.
• Refresh: Each --token call fetches a fresh value from the TapAuth API. TapAuth handles OAuth refresh server-side.
• Re-approval: If a grant is revoked or expired, re-run scripts/tapauth.sh <provider> <scopes> to create or re-show an approval URL.

Troubleshooting