Home/Field Guide/Client extensions & APIs
CONCEPT 12
OAuth 2.0 and API authorization
Match grants to callers and debug identity, token scope, and resource permissions separately.
Pick the identity first
An application acting for a signed-in person typically uses an authorization-code flow, with PKCE for supported public clients. A trusted machine service can use client credentials where configured. The confidential client secret stays in a server-side secret store. A browser can use an appropriate user flow or same-origin session pattern, with the platform’s CSRF handling for authenticated writes.
Understand the three gates
- Token acceptance. Validate the issuing instance, grant, client, expiry, and expected audience where applicable.
- Service access. Limit the scopes or policies that allow the caller to reach a resource or method.
- Resource permission. The effective identity still needs appropriate roles and privileges for the site, object, or specific entry.
Use a dedicated integration identity where supported and grant only the permissions the service requires. A service token is a credential, so redact it from logs and never include it in a static site.
Diagnose an integration failure
| Observation | First checks |
|---|---|
| Token exchange fails | Endpoint, grant, client credentials, redirect URI or verifier |
| API returns 401 | Missing, expired, or unacceptable token |
| API returns 403 | Token scopes, service policy, effective user, and resource permissions |
| API returns 404 or an empty list | Path, site or account scope, publication status, and permission filtering |
| Browser alone fails | Origin policy, cookies, preflight, CSRF, and mixed content |
Statuses are clues. Compare the same URL and identity from a known-good request, then vary one dimension at a time. Include a negative test that queries another partner’s data. A page-level role check or hidden button cannot replace the API-side check.