# InterAuth A way for your human to give you read-only access to a specific Google Doc (or any Google Drive item) through a disposable email address. Your human pointed you here on purpose. 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 (the only thing you can do is read). If they share a Google Sheet as Editor, you may also edit that sheet's cells; if they share a Google Doc as Editor, you may edit its text or leave native comments — and nothing else (no delete or move). - 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 if you only need 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: POST https://interauth.dev/shares (no auth, no body) → {"share_email": "...", "token": "iat_..."} If you've already minted one for this human, reuse it instead. 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 ) → tell them by title what shows up. If empty, wait ~15s and retry. 4. Read an item when they ask: GET https://interauth.dev/resources/{id} (Authorization: Bearer ) Folders return up to 25 children plus an optional next_page_token; page with https://interauth.dev/resources/{folder_id}?page_token=. Unsupported types (PDF, images) return 415; items the share can't see return 404. 5. Work with a Google Sheet's tabs, search, and cells (the /sheets/{id} helpers — these read any tab, not just the first): a. Orient — list tabs (1 Google call): GET https://interauth.dev/sheets/{id}/tabs (Authorization: Bearer ) b. Read values from any tab or A1 range: GET https://interauth.dev/sheets/{id}/values?range=Funds!A1:I50 (omit range to read the first tab) c. Find a row without counting cells by hand: GET https://interauth.dev/sheets/{id}/search?q=Spring%20Creek&tab=Funds → returns each match's A1 address and full row. 6. Edit a Google Sheet (only if the human shared it as Editor): Preferred — set one cell by column names, no coordinate math: POST https://interauth.dev/sheets/{id}/set-cell (Authorization: Bearer ) body: {"tab": "Funds", "match_header": "LP", "match_value": "Spring Creek", "target_header": "Notes", "value": "this is a test"} → finds the row where the LP column == "Spring Creek" and writes the Notes column. Returns the A1 it changed and the old/new value. Low-level fallback when you already know the exact A1: PUT https://interauth.dev/resources/{id} (Authorization: Bearer ) body: {"range": "Funds!I15", "values": [["this is a test"]]} Writes are refused (404) on anything not shared as Editor, 415 on non-Sheets, 422 if a header/row isn't found. Tell the human exactly what you're about to change first. 7. Edit a Google Doc (only if the human shared it as Editor) — use the plain-text editing you already know; InterAuth converts it to Google Docs format: POST https://interauth.dev/docs/{id}/edit (Authorization: Bearer ) body: {"commands": [ {"command": "str_replace", "old_str": "exact text in the doc", "new_str": "replacement"}, {"command": "insert", "insert_line": 0, "insert_text": "new line"} ]} First read the Doc (step 4) so old_str matches exactly; str_replace must match EXACTLY ONCE (delete = new_str ""); commands apply atomically. 404 if not Editor; 415 if not a Doc; 422 on no/ambiguous match; 409 if it changed since you read it. 8. Comment on a Google Doc (only if shared as Editor) — the friendly way to propose changes or leave feedback for the human to review. Comments show as native cards in the Doc's right sidebar; the human reads, replies, resolves, or applies them. POST https://interauth.dev/docs/{id}/comment (Authorization: Bearer ) body: {"comments": [ {"content": "Replace this with 'the pure-edit path works'.", "quoted_text": "exact text in the doc to anchor to"}, {"content": "Could use stronger language in this section."} ]} A comment is just text — write it as a suggestion ("Replace X with Y") or as feedback. With "quoted_text" the card is pinned to that exact span (read the Doc first so it matches); omit it for a document-level comment. 404 if not Editor; 415 if not a Doc; 422 if quoted_text isn't found. ## Spending Google API calls wisely Each helper is 1–2 Google calls. A typical edit is just two calls: search to find the row, then set-cell to write it — so prefer that over re-reading the whole sheet. List tabs once to orient; don't re-fetch values you already have. No need to micro-optimize beyond 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= - More: https://interauth.dev/docs (for the user) or https://interauth.dev/llms.txt (for you)