ReferenceSkillsSkill authentication

Skill

Skill authentication

Keep Skill credentials in XMEMO_KEY or the supported device-login flow, never in public output.

Credential resolution precedence

The standalone Skill runtime resolves credentials using strict three-tier precedence. Managed external secrets always take priority over local files, ensuring tokens are never duplicated onto disk when an environment secret is provided.

  • 1. XMEMO_KEY: Environment variable or managed secret store (Doppler, 1Password, Vault). Preferred; never copied to local credential files.
  • 2. Meta Muse Secure Vault: Surrogate vault resolution in supported Meta Muse environments.
  • 3. Local credential file: ~/.xmemo/skill-credentials.json (or $XMEMO_CREDENTIALS_PATH), read only as a fallback when environment credentials are unset.
  • OpenClaw egress requirement: OpenClaw egress is a transport requirement handled inside the XMEMO_KEY branch (auth-state.mjs). If an OpenClaw sentinel is detected, egress proxy reachability is enforced; it is transport verification within XMEMO_KEY, not a separate credential source.
  • Zero token exposure: Commands and doctor diagnostics never print active tokens or secret prefixes.
# Preferred: provide credential via environment or secret store
export XMEMO_KEY='<your-xmemo-token>'

# Inspect active credential source and scopes without printing secrets:
node scripts/xmemo-skill.mjs auth status --verify

Device sign-in and informed plaintext choice

When no managed environment key exists, interactive setup uses browser-based device authorization. The user approves access in the browser, and the browser never displays the bearer token value.

  • Explicit plaintext consent: The login command requires --allow-plaintext to confirm informed consent for saving the token unencrypted on the local machine.
  • Restricted file permissions: ~/.xmemo/skill-credentials.json is created with 0600 POSIX permissions (read-write by owner only).
  • Safe stdin import: Import an existing token via standard input using auth add --from-stdin --allow-plaintext, avoiding command-line arguments and shell history logging.
  • Device authorization endpoints: POST /v1/auth/device/start (initiate flow), POST /v1/auth/device/token (poll and exchange), POST /v1/auth/token/validate (verify), POST /v1/auth/token/revoke-self (revoke).
# Start interactive device login (requires explicit plaintext flag):
node scripts/xmemo-skill.mjs login --allow-plaintext

# Or pipe an existing token securely from standard input:
printf '%s' "$XMEMO_KEY" | node scripts/xmemo-skill.mjs auth add --from-stdin --allow-plaintext

# Verify active session status:
node scripts/xmemo-skill.mjs auth status --verify

Temporary registration boundaries

For unattended environments or when a human declines formal sign-in, the Skill can register a temporary memory sandbox. Temporary memory is strictly bounded and intended only for short-lived operational continuity.

  • Unattended or declined only: node scripts/xmemo-skill.mjs register --reason <unattended|declined> --allow-plaintext.
  • Capacity ceiling: Bounded to a maximum of 100 items.
  • Retention TTL: 14-day inactivity TTL and a 30-day absolute maximum lifetime.
  • Two-phase claim handoff: Emits a bind URL (bind_url) allowing a human operator to claim the temporary account and bind it to formal credentials.
  • Claim management commands: auth claim-status inspects pending claims, auth claim-confirm accepts formal token handoff, and auth claim-deny declines the bind.
  • Sandbox restrictions: Temporary accounts cannot capture restart snapshots (restart-snapshot) or access Knowledge bases (recall-context --include_knowledge true).
# Register temporary sandbox:
node scripts/xmemo-skill.mjs register --reason unattended --allow-plaintext

# Inspect and manage claim binding:
node scripts/xmemo-skill.mjs auth claim-status --allow-plaintext
node scripts/xmemo-skill.mjs auth claim-confirm --allow-plaintext
node scripts/xmemo-skill.mjs auth claim-deny --allow-plaintext

Logout and provider-appropriate revocation

Logging out unlinks the local credential file and self-revokes the active session token on the server. External secret providers must be managed in their own environments.

  • Local session logout: node scripts/xmemo-skill.mjs logout removes ~/.xmemo/skill-credentials.json and calls /v1/auth/token/revoke-self.
  • External environment token: When XMEMO_KEY supplies the active credential, logout leaves that token intact unless --revoke-environment-token is explicitly passed.
  • Local removal is not global revocation: Removing the local skill directory or logging out locally does NOT revoke tokens stored in cloud secret vaults, CI/CD runners, or other machines.
  • External cleanup: Unset XMEMO_KEY in the shell or delete the secret from your secret manager to permanently de-authorize access.
# Log out and revoke local credential file:
node scripts/xmemo-skill.mjs logout

# Log out and revoke external environment token remotely:
node scripts/xmemo-skill.mjs logout --revoke-environment-token

Skill authentication

Skills are the instruction-and-command lane for agents that do not mount a hosted MCP server directly.

Open XMemo Skills

Source: XMemo Skills