How it works

1. The problem has two clocks

Each guide separates “working with your own account” (usually minutes) from “any customer can connect” (sometimes weeks). Most launch surprises live in the gap: user caps on unverified apps, marketplace reviews, security assessments, partner approvals, or a customer admin who must approve the app.

2. Archetypes

The top-level bucket: what kind of gate stands between registration and production.

3. Friction flags

Specific requirements that cut across archetypes. A guide only carries the flags its evidence supports.

Paid plan required

API or app registration needs a paid tier, credits, or edition.

Business verification

Provider verifies a legal entity, business documents, or a company page.

Domain verification

You must prove you own the domain behind your homepage or redirect URIs.

Policy URLs required

Public privacy policy, terms of service, or support URL on your domain.

Manual app review

A human at the provider reviews the app before it can be distributed.

Demo video

A screencast showing the OAuth flow and how each scope is used.

Security assessment

Independent security assessment (e.g. CASA), often paid and recurring.

User cap until approved

Only a limited number of users/workspaces can connect before approval.

Partner application

You apply for access to an API product; approval is discretionary.

Customer admin consent

Your customer's admin must approve or install the app before users can connect.

Per-customer setup

Each customer org/store/subdomain needs its own client, install, or endpoint.

Redirect URI rules

HTTPS-only, exact-match, no localhost, or limited number of redirect URIs.

Token lifecycle gotchas

Expiring/rotating refresh tokens, no refresh tokens, or revocation surprises.

Marketplace listing optional

A directory/marketplace listing exists but isn't needed to connect users.

4. Difficulty is computed, not written

Starting from the archetype, a guide moves to High friction if it needs a security assessment or partner application, at least Involved if the production wait is 3+ days, and High friction at 21+ days.

• Quick — Self-serve. You can ship the same day.
• Moderate — Self-serve with extra configuration, policies or an optional review.
• Involved — Expect reviews, admin approvals or per-customer setup measured in days.
• High friction — Audits, partner approval or multi-week reviews that you can't speed up.

5. When documentation is thin or missing

• Evidence coverage — the share of claims backed by our tests or official docs (community reports count half). Below 40%, the guide shows Unrated · low evidence and a warning instead of a difficulty rating.
• Assumed steps — steps inferred from standard OAuth practice rather than the provider's docs are tagged Assumed and can never be graded better than Uncertain.
• No invented URLs — console/docs/endpoint URLs are left empty when research didn't find them, and URLs that never appeared in a source are listed as open questions.
• No public OAuth is a verdict of its own, not a difficulty level.
• Ask the provider — open questions become a ready-to-send message to the provider's developer support or partner channel.

6. Evidence grades

“Tested” never means we created an app or passed a review. It means our agent observed the claim itself — e.g. fetching the provider's discovery document, or sending a deliberately invalid client id to the live authorize endpoint and recording how it responds.

7. The live investigator

1. 1
   Checking API key & model

   Validates the API key and model with a metadata call that costs no tokens, so a bad key never wastes a run.

2. 2
   Identifying the app

   Resolves the name or URL to a product, its official domains and its OAuth docs (one grounded search call). If it isn't sure the app offers OAuth, one availability check runs first; if no public OAuth is found, the agent writes a short guide about the alternative (API keys, partner programs) instead of paying for full research.

3. 3
   Researching docs, reviews & field reports

   Three parallel grounded research tracks: registration mechanics, the review/verification path, and field reports & recent policy changes. The mechanics track also reads the official docs page directly.

4. 4
   Resolving & classifying sources

   Resolves Google's grounding redirects to real URLs, de-duplicates them, and classifies each as official (provider-owned domain) or community. Citations are inserted into the notes as [S#].

5. 5
   Writing the structured guide

   A separate structured-output call turns the cited notes into the guide schema. Invalid JSON gets one cheap repair call; research is checkpointed so a retry never repeats it.

6. 6
   Probing live endpoints & grading evidence

   Code, not the model, grades evidence: model-claimed 'tested' is downgraded, 'source-backed' without an official citation is downgraded. Then credential-free probes hit the live discovery, authorize and token endpoints and the console/docs pages.

7. 7
   Publishing the guide

   The guide is saved under a short link and can also be shared as a self-contained portable link or Markdown.

8. Limitations

• No agent creates real OAuth apps or submits reviews; console-only facts are source-backed at best.
• Review timelines are rarely published; estimates are conservative ranges and marked uncertain where unsupported.
• Live guides reflect what web search surfaces at that moment; paywalled or login-only docs are invisible to it.
• Probes confirm endpoints are live and how they reject bad input — not that your configuration will be approved.