docs(api): show the PKCE flow instead of the device flow

[olivermeyer]

Why?

We are deciding whether external API users should authenticate with the device flow or with the authorization code flow plus PKCE. The argument is easier to have against concrete text than in the abstract, so this rewrites the guide's Authenticate section the PKCE way to show what users would actually have to do. This is a proposal for discussion, not a decided change — do not merge before we pick a direction.

How?

Replaces steps 1 and 2 of the Authenticate section with the PKCE pair, the /authorize URL, and the authorization_code exchange, and renumbers the rest. The refresh step, the GET /v1/me check, and everything from "Find out what the application expects" onward are untouched, because they do not depend on how the first token was obtained.

Three consequences worth weighing before we choose:

1. PKCE adds a dependency. The guide now needs openssl for the random verifier and its SHA-256 challenge. The device flow needed only curl and jq.
2. PKCE needs a registered redirect URI, and something has to receive the redirect. The guide asks the reader to copy code out of the address bar, which works for a one-time login but is not unattended. A real integration must run a local listener, so this flow cannot work on a machine with no browser — precisely what the device flow was for.
3. In exchange, PKCE uses the organization-enabled interactive client, so its tokens carry org_id and a real role today. Device-flow clients cannot use Auth0 Organizations, which is the cause of the empty role claim tracked in aignostics/infrastructure#3918.

Verified: sphinx-build succeeds, the embedded hello_aignostics.sh passes bash -n, the PKCE derivation matches the RFC 7636 test vector, and no device-flow references remain in docs/.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.
see 7 files with indirect coverage changes

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud