> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herodotus.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Herodotus Auth AI Skill

> Vendor-neutral AI playbook for authenticating to Herodotus Cloud programmatically with an EVM wallet (EIP-712 → Bearer access token → API key). Required precondition for every Herodotus API skill.

**AI Skills**

<div style={{ marginBottom: "14px", display: "flex", gap: "10px", flexWrap: "wrap" }}>
  <button
    style={{
  background: "linear-gradient(90deg, #0C68F3 0%, #5B8CFF 100%)",
  color: "#FFFFFF",
  border: "none",
  borderRadius: "10px",
  padding: "10px 14px",
  fontWeight: 600,
  cursor: "pointer"
}}
    onClick={async () => {
  const text = await fetch("https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md").then((r) => r.text());
  await navigator.clipboard.writeText(text);
}}
  >
    Copy Full Skill
  </button>

  <button
    style={{
  background: "#0F172A",
  color: "#FFFFFF",
  border: "1px solid #334155",
  borderRadius: "10px",
  padding: "10px 14px",
  fontWeight: 600,
  cursor: "pointer"
}}
    onClick={async () => {
  const text = await fetch("https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md").then((r) => r.text());
  const blob = new Blob([text], { type: "text/markdown;charset=utf-8" });
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url;
  a.download = "herodotus-ai-skill-herodotus-auth-v1.md";
  a.click();
  URL.revokeObjectURL(url);
}}
  >
    Download Skill
  </button>
</div>

Use this playbook when an AI assistant or CLI needs to authenticate to Herodotus Cloud programmatically using an EVM wallet — exchanging an EIP-712 challenge for a Bearer access token, then retrieving an API key.

This is the **first skill to load** for any non-browser Herodotus integration: the Atlantic, Storage Proof, Data Processor, and Satellite skills all assume an API key is already in hand.

<Tabs>
  <Tab title="Claude Code">
    Global:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude
    ```

    Or project-local:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project
    ```

    Or inside Claude Code:

    ```bash theme={null}
    /plugin marketplace add HerodotusDev/ai-skills
    /plugin install herodotus-skills@herodotus
    ```

    Or via the Claude CLI:

    ```bash theme={null}
    claude plugin marketplace add HerodotusDev/ai-skills
    claude plugin install herodotus-skills@herodotus
    ```

    Then use: `/herodotus-skills:herodotus-auth`
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    mkdir -p .cursor/skills/herodotus/herodotus-auth
    curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md \
      -o .cursor/skills/herodotus/herodotus-auth/SKILL.md
    ```
  </Tab>

  <Tab title="Codex">
    **Global:**

    ```bash theme={null}
    mkdir -p ~/.codex/skills/herodotus/herodotus-auth
    curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md \
      -o ~/.codex/skills/herodotus/herodotus-auth/SKILL.md
    ```

    **Or project-local:**

    ```bash theme={null}
    mkdir -p .codex/skills/herodotus/herodotus-auth
    curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md \
      -o .codex/skills/herodotus/herodotus-auth/SKILL.md
    ```
  </Tab>

  <Tab title="Antigravity">
    ```bash theme={null}
    mkdir -p .agent/skills/herodotus/herodotus-auth
    curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md \
      -o .agent/skills/herodotus/herodotus-auth/SKILL.md
    ```
  </Tab>

  <Tab title="Install All">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash
    ```
  </Tab>
</Tabs>

## What this skill teaches

* The full wire protocol: `GET /auth/web3/challenge` → sign EIP-712 → `POST /auth/web3/session` (with `channel: "bearer"` in the JSON body) → `GET /api-keys` → `POST /auth/refresh-token`.
* Channel-binding semantics — why a Bearer-issued JWT must never be presented via cookie (and vice versa).
* A bring-your-own-signer model: the protocol is signer-agnostic. The reference example uses viem; KMS, hardware wallets, MetaMask, and ethers all work without changing the skill.
* Anti-hallucination guardrails: do not invent endpoints, do not hardcode the EIP-712 domain/types/statement, do not assume a default `projectId`.

For the human-readable walkthrough of the same flow, see [Programmatic wallet authentication](/documentation/authentication#programmatic-wallet-authentication).