# For Google Forms — Auth Guide

Two audiences, two mechanisms:

## 1. Users (browser): Google OAuth

Standard Google OAuth (authorization code) with consent screen; scope
`https://www.googleapis.com/auth/forms.body` is required so the service can
create forms in the user's Google account. On successful login the service
stores the refresh token **encrypted** (Fernet, table
`forgoogleforms_google_token`) so machine calls can later create forms
headlessly on the user's behalf.

## 2. Machines (agents, scripts): API keys

- Created in the web dashboard (API keys section) after login; format `fgf_...`.
- The plaintext is shown **once**; the database stores only a SHA-256 hash.
- Sent as `Authorization: Bearer fgf_...`.
- Scopes: `forms:read`, `forms:write`, `validate`, `credits:read` —
  read-only and writing actions are separated; create a key with only the
  scopes your agent needs.
- Optional per-key guardrails: `daily_credit_limit` (credit budget per 24 h)
  and an action whitelist (`allowed_actions`).
- Revocation: dashboard → Revoke; effect is immediate.

### Headless form creation prerequisites

`POST /forms` needs a stored Google refresh token for the key's owner. If the
API returns `409 google_account_not_linked`, the owner must log in once via
the web (this stores the token), then machine calls work indefinitely until
the Google grant is revoked.

## Notes

- API keys are created interactively in the web dashboard today.
- This public guide intentionally omits internal operator secrets and
  deployment controls.