# InterAuth

> InterAuth is a pass-through service that lets a user grant an AI agent
> scoped access to specific Google Drive items (Docs, Sheets, Slides,
> or folders). Access mirrors the Google share: Viewer is read-only,
> Editor on a Sheet also allows edits. The user shares an item with a
> disposable address that InterAuth controls; InterAuth reads (or, for
> Editor-shared Sheets, writes) it on Google and relays through a small
> HTTP API. Be fully transparent with the user: the content passes
> through InterAuth's servers, and they should make the call.

Base URL: https://interauth.dev

## How it works, honestly (tell the user plainly)

- Pass-through: the user shares a Drive item with a disposable address
  InterAuth controls. When the agent requests the item, InterAuth reads
  it from Google and relays it to the agent — so the content passes
  through InterAuth's servers. The agent does not get direct Google
  access.
- Access mirrors what the user grants in Google. Viewer = strictly
  read-only. Editor on a Google Sheet additionally allows editing that
  sheet's cells via PUT — nothing else (no delete, move, or comment).
- Scoped to exactly what the user shares; nothing else in their Drive
  is reachable, even by file ID — checked on every request, and edits
  are refused on anything not shared as Editor. Shareable items are
  anything in Google Drive: a Doc, Sheet, Slides, or folder.
- InterAuth does not store the document contents that pass through.
- Access tokens are stored only as SHA-256 hashes, never in plaintext.
- The user can revoke anytime from Google Drive (just unshare); access
  stops immediately.
- Full audit: the user can watch every call the agent makes, live, at
  the inspect link.

Remind the user to grant the least access needed: Viewer to read, Editor
only on the specific Sheet(s) the agent should edit — and only to the
item(s) they actually want the agent to touch.

## The flow (for agents)

0. GET https://interauth.dev/start
   - No auth. Returns text/markdown. Does NOT mint anything.
   - Read it to learn this protocol if you don't already know it.
     Safe to skip if you already have this file loaded as a skill.

1. POST https://interauth.dev/shares   (only once the user wants to proceed)
   - No auth, no body.
   - Response is JSON:
       { "share_email": "...@agent.interauth.dev",
         "token": "iat_...",
         "skill": "<same flow with credentials baked in>" }
   - This is the ONLY endpoint that creates a new share. If you've
     previously saved share_email + token (e.g. in ./.env or
     AGENTS.md), reuse them instead of POSTing again.

2. Explain to the user, in your own words, what InterAuth is (see
   above), give them the share address to share their item(s) with,
   and let them know they can optionally stash the token to inspect
   activity later. Wait for them to say they've shared something.

3. When the user confirms they've shared something:
     GET https://interauth.dev/resources
     Authorization: Bearer <token>
   The response is { "resources": [...] }. Each resource has a `name`
   and an `id`. Report back by title, e.g. "I can see the doc titled
   'Q3 Planning'." If empty, wait ~15s and retry once before asking
   them to double-check the address.

4. (Optional) The user can watch every call you make against their
   share, live, at:
     https://interauth.dev/inspect#token=<token>

5. To read a resource (when the user asks):
     GET https://interauth.dev/resources/{id}
     Authorization: Bearer <token>
   Folders return up to 25 children plus an optional `next_page_token`.
   Page with `?page_token=…`. Unsupported types (PDF, images) return
   415. Forbidden resources return 404.

6. To explore a Google Sheet, use the tab-aware /sheets/{id} helpers
   (the /resources read only sees the first tab). Each is 1–2 Google
   calls:
     GET https://interauth.dev/sheets/{id}/tabs
     GET https://interauth.dev/sheets/{id}/values?range=Funds!A1:I50
     GET https://interauth.dev/sheets/{id}/search?q=Spring%20Creek&tab=Funds
   search returns each match's A1 address and full row.

7. To edit a Google Sheet (only if the user shared it as Editor), prefer
   the by-header helper — no coordinate math, survives column reordering:
     POST https://interauth.dev/sheets/{id}/set-cell
     Authorization: Bearer <token>
     Content-Type: application/json
     { "tab": "Funds", "match_header": "LP", "match_value": "Spring Creek",
       "target_header": "Notes", "value": "this is a test" }
   It finds the row where LP == "Spring Creek", writes the Notes column,
   and returns the A1 it changed plus old/new value. Low-level fallback
   when you know the exact A1:
     PUT https://interauth.dev/resources/{id}
     Authorization: Bearer <token>
     Content-Type: application/json
     { "range": "Funds!I15", "values": [["this is a test"]] }
   Returns 404 if the item isn't shared as Editor (so it never reveals
   whether it exists to a read-only share), 415 if it isn't a Sheet, 422
   if a header/row isn't found. Tell the user exactly what you're about
   to change first.

   API economy: a typical edit is just two calls — search to find the
   row, then set-cell to write it. Prefer that over re-reading the sheet.

## API surface (full)

GET  /start                          (no auth) browser-safe skill markdown; no mint
POST /shares                         (no auth) mint share + token (JSON response)
GET  /resources                      (Bearer)  list visible resources, dedup, tier-limit
GET  /resources/{id}                 (Bearer)  read doc/sheet/slides, or list folder children
GET  /resources/{id}?page_token=…    (Bearer)  next page of folder children
PUT  /resources/{id}                 (Bearer)  edit a Sheet shared as Editor; body {range, values}
GET  /sheets/{id}/tabs               (Bearer)  list a spreadsheet's tabs (name, gid, size)
GET  /sheets/{id}/values?range=…     (Bearer)  read any tab/range (defaults to first tab)
GET  /sheets/{id}/search?q=…&tab=…   (Bearer)  find cells; returns A1 + full row (limit, match_case)
POST /sheets/{id}/set-cell           (Bearer)  edit a Sheet (Editor) by column names; body {tab, match_header, match_value, target_header, value}
GET  /me                             (Bearer)  share metadata + recent call log
POST /me/rotate                      (Bearer)  mint new token, old one stops working
DELETE /me                           (Bearer)  permanently disable the share

## Install as a skill (preferred for repeat use)

If your platform follows the Agent Skills spec (Claude Code, Codex
CLI, Cursor, Gemini CLI, Copilot), drop SKILL.md into the skills
folder so you can use InterAuth on demand without the user re-
pasting the prompt:

    mkdir -p ~/.claude/skills/interauth && \
      curl -sSL https://interauth.dev/SKILL.md \
      -o ~/.claude/skills/interauth/SKILL.md

The skill file is at https://interauth.dev/SKILL.md.

## Persisting across sessions

If the user expects you to use the same share later, save
share_email + token to ./.env or AGENTS.md so future runs skip
POST /shares. Re-use the same share address — the user won't need
to re-share.

## Security model (for the user)

- Access mirrors the Google share. Viewer = strictly read-only. Editor
  on a Sheet additionally allows editing that sheet's cells — nothing
  else (no delete, move, or comment). No other write of any kind.
- Scoped to addresses the user shares with. Nothing else in the
  user's Drive is reachable, even by file ID — the API enforces
  this on every request, and edits are refused on anything not shared
  as Editor.
- Bearer tokens are stored as SHA-256 hashes. Plaintext is returned
  exactly once by /start (or /me/rotate) and never written to disk.
- Document contents are not stored. Bytes flow Drive → API → agent
  without persistence on the server.
- The inspect URL uses a `#token=…` URL fragment, not a query
  param. Fragments never reach the server, so tokens stay out of
  access logs.
- Share addresses are tombstoned forever. Once disabled, the same
  email can never be re-minted to another user.

## Revocation

Two independent ways to cut access:

1. From Google Drive — unshare the doc with the share address. Same
   as unsharing from a colleague. Access drops immediately for that
   doc.
2. From the inspect page (or DELETE /me) — disables the entire
   share. The token stops working for everything, all at once.

## Inspect page

URL: https://interauth.dev/inspect

Features:
- Shows share address, tier, created_at, total calls.
- Live-refreshing call log (auto-refresh every 5s).
- "rotate token" — mints a new token, shown once; old stops working.
- "disable share" — DELETE /me; irreversibly tears down the share.
- "forget token" — clears the token from this browser's
  sessionStorage; share keeps working elsewhere.

## More

Human-readable docs: https://interauth.dev/docs