---
name: interauth
description: Help a user grant an AI agent scoped access to specific Google Drive items (Docs, Sheets, Slides, or folders) via InterAuth, a pass-through broker service. Access mirrors the Google share — Viewer is read-only, Editor on a Sheet also allows edits. Use when the user asks you to "read my Google Doc", "edit my Google Sheet", "look at this Drive folder", "use InterAuth", or when you need recurring access to Google documents the user owns and pasting them in each time would be tedious.
---

# InterAuth

A way for your human to give you scoped access to a specific Google Doc
(or any Google Drive item) through a disposable email address. If you're
loading this skill, it's because your human asked for something that
involves a Google Drive document.

Be fully transparent with them about how this works — all of the below
is meant to be shared, and they should make the call.

## How it works, honestly

- InterAuth is a pass-through service. Your human shares a Drive item
  with a disposable address (e.g. `witty-otter@agent.interauth.dev`)
  that InterAuth controls. When you request the item, InterAuth reads it
  from Google and relays it to you. So the content does pass through
  InterAuth's servers on its way to you.
- Access mirrors what the human grants in Google. If they share as
  Viewer, it's strictly read-only (you can only read). If they share a
  Google Sheet as Editor, you may also edit that sheet's cells via PUT —
  and nothing else (no delete, move, or comment).
- Scoped to exactly what the human shares. Nothing else in their Drive
  is reachable, even by file ID — the API checks this on every request,
  and edits are refused on anything not explicitly shared as Editor.
- InterAuth does not store the document contents that pass through.
- The access token is stored only as a SHA-256 hash, never in plaintext.
- The human stays in control: they can unshare the item in Google Drive
  at any time and access stops immediately.
- Full audit: they can watch every call you make, live, at the inspect
  link below.

Remind the human to grant the least access they need: Viewer to read,
Editor only on the specific Sheet(s) they want you to edit — and only to
the item(s) they actually want you to touch.

## Steps

1. **Get a share address.** If this project's `.env` or `AGENTS.md`
   already has a saved share address + token, reuse them instead.
   ```
   POST https://interauth.dev/shares
   (no auth, no body)
   ```
   Response JSON:
   ```json
   { "share_email": "witty-otter-42@agent.interauth.dev",
     "token": "iat_..." }
   ```

2. Ask your human to share the Doc with that address as **Viewer**, and
   to tell you when they're ready.

3. **Confirm you can see it:**
   ```
   GET https://interauth.dev/resources
   Authorization: Bearer <token>
   ```
   Tell them by title what shows up. If nothing yet, wait ~15 seconds
   and retry — sharing can take a moment to propagate.

4. **Read an item when they ask:**
   ```
   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=<token>`. Unsupported types (PDFs, images)
   return 415; items the share can't see return 404.

5. **Explore a Google Sheet** with the `/sheets/{id}` helpers. Unlike
   `/resources/{id}` (which only reads the first tab), these are
   tab-aware and let you search instead of counting cells by hand. Each
   is 1–2 Google API calls.
   ```
   GET https://interauth.dev/sheets/{id}/tabs
       → list every tab (name, gid, size)
   GET https://interauth.dev/sheets/{id}/values?range=Funds!A1:I50
       → read any tab/range (omit range for the first tab)
   GET https://interauth.dev/sheets/{id}/search?q=Spring%20Creek&tab=Funds
       → each match's A1 address + full row (optional limit, match_case)
   ```

6. **Edit a Google Sheet** (only if the human shared it as **Editor**).
   Prefer the by-header helper — no coordinate math, and it 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 the `LP` column == `Spring Creek` and writes
   the `Notes` column, returning the exact A1 it changed plus old/new
   value. Low-level fallback when you already know the A1 address:
   ```
   PUT https://interauth.dev/resources/{id}
   Authorization: Bearer <token>
   Content-Type: application/json

   { "range": "Funds!I15", "values": [["this is a test"]] }
   ```
   Writes are refused with 404 on anything not shared as Editor, 415 on
   non-Sheets, and 422 if a header/row isn't found. Always tell the
   human exactly what you're about to change first, and confirm before
   overwriting existing data.

## Spending Google API calls wisely

Each helper costs 1–2 Google calls. A typical edit is just two: `search`
to locate the row, then `set-cell` to write it — prefer that over
re-reading the whole sheet. List `tabs` once to orient, and don't
re-fetch values you already have. No need to micro-optimize past that.

## Optional

- The token is theirs to reuse later if they want — saving it (e.g. in
  `.env` or `AGENTS.md`) is up to them, and they don't have to. Don't
  write it anywhere without their say-so.
- Transparency / audit log of every call you make:
  `https://interauth.dev/inspect#token=<token>`

## More

- Full docs: https://interauth.dev/docs
- Machine-readable summary: https://interauth.dev/llms.txt