Document the complete set of auth grant types, with a how-to per type

[allister-beamable]

docs/api/authenticating.md on api/v1.0 currently covers four ways to find a token you already have — create a guest account, log in with email and password, beam me, and snooping Portal in browser devtools. That set is inherently open-ended, and the page now says so ("the methods below are the most common").

What is missing is the genuinely closed set underneath it: the grant_type values the platform accepts. Nothing in the docs enumerates them, and the machine-readable reference cannot answer it either.

The set is closed and knowable

BeamableBackend, core/src/main/scala/com/disruptorbeam/clients/auth/AuthClient.scala, tokenRequest — a total match on grant_type.toLowerCase, with everything else falling through to InvalidGrantTypeError:

grant_type	Required fields	Notes
guest	none	anonymous account creation; the one public, unauthenticated route
password	username, password	developer accounts included
refresh_token	refresh_token
third_party	third_party, token	ThirdPartyAuthProvider on WebSDK documents only Facebook and Google
external	provider_service, external_token; optional provider_namespace, challenge_solution	this is Federated Identity
device	device_id	note the value is device, not device_id — device_id is the field name
authorization_code	client_id, code, redirect_uri

Seven, not the six one might recall from memory. authorization_code is easy to overlook, and the device / device_id distinction is exactly the kind of thing a reader cannot guess.

Why the OpenAPI reference does not cover it

docs/assets/beamable-oapi.json on api/v1.0 declares grant_type as bare {"type": "string"} with no enum. So the /basic/auth/token reference — the place that ought to be authoritative — does not constrain it, and the RapiDoc page renders a free-text field. The property set on TokenRequestWrapper hints at the families, but that is reverse-engineering a schema rather than reading documentation.

This is arguably the higher-leverage half of the fix: adding the enum to grant_type upstream in the OpenAPI generator would make the reference self-documenting for every consumer, not just for readers of the prose page. Worth checking with the SDK team whether that is cheap.

What exists today, scattered

• WebSDK AuthService — four login param types (email, third-party, external identity, refresh token). SDK surface rather than grant types, and auto-generated, so not editable from this repo
• WebSDK ThirdPartyAuthProvider — Facebook and Google only
• Unity identity.md — RecoverAccountWithEmail and RecoverAccountWithThirdParty, then defers to "the individual sign in method pages"
• Unreal — federated-login.md, identity.md, online-subsystem-identity.md

So per-engine how-tos partly exist; the API-level table that ties them together does not.

Proposed shape

A table on api/v1.0 like the one above — grant type, required fields, one-line purpose — with each row linking out to the per-engine how-to where one exists. That keeps the exhaustive list in one place (the API branch, where the grant types actually live) without duplicating per-engine instructions into it.

Open questions worth settling before writing:

• Is authorization_code intended for external consumers, or is it internal-only plumbing? If internal, the table should say so rather than omit it
• Same question for device — is device-ID auth a supported integration path or a legacy flow?
• Cross-branch links from api/v1.0 into Unity-6.0 / Unreal-2.3 cross Mike version boundaries, so they must be absolute help.beamable.com URLs and will need revisiting as versions roll

Not bite-size

Seven types, an upstream OpenAPI change, and cross-branch linking. Deliberately unlabeled bite-size; the OpenAPI enum addition might be, if split out.

Surfaced while copyediting api/v1.0 for #127.