interauth

docs

Everything an operator (or a curious agent) needs to use InterAuth.

What it is

InterAuth gives an AI agent scoped access to specific Google Docs or folders, without sharing your whole Drive. You mint a disposable email address, share the item with it, and the agent reads it through a small HTTP API with a bearer token. Access mirrors your Google share: share as Viewer and it's strictly read-only; share a Google Sheet as Editor and the agent can also edit that sheet's cells — nothing else.

Every call the agent makes is logged per-share and viewable live on the inspect page. Revoke from Google Drive at any time, or disable the share entirely from the inspect page — access drops immediately.

The flow

  1. Paste the prompt from the home page into your agent (Claude Code, Cursor, Amp, or anything that can make HTTP calls). Or install the skill once and skip the prompt forever.
  2. The agent visits /start to learn the protocol (read-only — no mint happens), then calls POST /shares to mint:
    • a fresh share address like witty-otter-42@agent.interauth.dev
    • a bearer token like iat_…
  3. The agent tells you the address and the token. You share a Google Doc or folder with that address — Viewer to read, or Editor on a Sheet if you want the agent to edit it.
  4. You tell the agent you're done. It calls /resources, sees the doc, and confirms by title.
  5. The agent gives you an inspect URL. Open it to watch every API call the agent makes against your share, in real time.
  6. You ask the agent to do something with the doc.

Install as a skill (optional)

If your agent follows the Agent Skills spec (Claude Code, Codex CLI, Cursor, Gemini CLI, GitHub Copilot), you can install InterAuth once and skip the prompt-paste step:

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

The file lives at /SKILL.md. Same skill works across all the major agents — the spec is portable. Once installed, the agent loads InterAuth on demand whenever the user asks to share a Google Doc.

API surface

Base URL: https://interauth.dev. All endpoints return JSON unless noted.

GET/startauth: none

Browser-safe skill markdown for the agent. Does NOT mint anything — explains the protocol and tells the agent to POST /shares when it actually needs a share.

POST/sharesauth: none

Mints a fresh share address + bearer token. Returns JSON: { share_email, token, skill }. The skill field is the same markdown an agent would read from /start, but with credentials baked in.

GET/resourcesauth: Bearer iat_…

Lists every resource the share address has been granted access to. Folders are deduped (one entry per shared folder, not one per child).

GET/resources/{id}auth: Bearer iat_…

Reads one resource. Docs/Sheets/Slides are returned as text/JSON. Folders return up to 25 children plus an optional next_page_token. Returns 404 if the share can't see it, 415 for unsupported types (PDF, image, etc.).

PUT/resources/{id}auth: Bearer iat_…

Edits a Google Sheet shared as Editor. Body: { range, values } (A1 range + rows of cells). Returns 404 if the item isn't shared as Editor (so it never leaks existence to a read-only share), 415 if it isn't a Sheet.

GET/meauth: Bearer iat_…

Returns the share's metadata (address, tier, created_at, total calls) plus the 100 most-recent agent API calls.

POST/me/rotateauth: Bearer iat_…

Mints a new bearer token for this share. The old token stops working immediately. Same address, same call log. The new token is returned exactly once.

DELETE/meauth: Bearer iat_…

Permanently disables the share. The token stops working, the Google Group is deleted, and the address can never be re-minted to another user.

What we store, and don't

  • Tokens are stored as SHA-256 hashes. The plaintext is returned once by /start (or /me/rotate) and never written to disk.
  • Document contents are not stored. Bytes flow Drive → API → agent without persistence on our side.
  • We log one row per HTTP request the agent makes (endpoint, resource id, status, latency). This is what you see on the inspect page.
  • Share addresses are tombstoned forever. Once you disable a share, its email can never be re-minted to another user — even if Drive's old ACL entries persist somewhere.

The inspect page

Visit /inspect and paste your token (or follow the #token=…link the agent prints). The page shows the share's address, tier, every API call so far, and lets you:

  • refresh the call log on demand (otherwise auto-refreshes every 5s)
  • forget token— clears it from this browser's sessionStorage; the share keeps working elsewhere
  • rotate token — issues a new token, shown once; old token stops working
  • disable share — irreversibly tears the share down

The token is passed via the URL fragment (#token=…), not a query string. Fragments never reach our servers, so the token stays out of access logs.

Revoking access

You have two independent ways to cut access:

  • From Google Drive: unshare the doc with the share address, same as you would for any colleague. Access drops immediately for that doc.
  • From the inspect page: disable the share. The token stops working for everything, all at once.

For LLMs

A plain-text version of this page, formatted for AI consumption, lives at /llms.txt.

← back

© 2026 interauth