App Integration OAuth Tutorial: Authorization Code, PKCE, and Minimal Scopes
2026-11-17 · 原创·功能教程
App Integration OAuth Tutorial: Authorization Code, PKCE, and Minimal Scopes
This tutorial is for developers who are new to application integration and want users to authorize your application. The goal is to connect the app so that it can act after a user grants authorization. Use the OAuth authorization code flow with PKCE, and start from `/docs#docs-oauth`. Before making changes, identify whether your app is a public client and list only the business scopes that are actually required.
1. Prepare
- Read the integration documentation at `/docs#docs-oauth`.
- Confirm whether the app is a public client. Public clients must use S256.
- Define the minimal scope set by business need. Do not request unrelated permissions.
- Decide where credentials will be stored. Balance and usage scopes are separate, and ext tokens must never be exposed in browser code.
- For a first integration, document why each requested scope is needed so the scope list stays focused on the current feature.
2. Configure the authorization flow
1. Use the OAuth authorization code flow with PKCE.
2. For public clients, configure S256 as required.
3. Request only the scopes your application needs for the current feature.
4. Handle the authorization result outside browser code so that ext tokens are not placed in frontend code.
5. Keep the authorization step separate from usage review: authorization confirms user consent, while usage review confirms app-scoped activity.
3. Review the result
After a user authorizes the application, verify that the user completed the authorization and that the app received only the requested scopes. Check app-scoped usage for your application. When reviewing balance and usage, treat them as independent permissions and confirm each one separately. If a scope is not needed for the feature being tested, remove it from the request and validate the flow again.
4. Safety notes
Never expose ext tokens in browser code. Do not expand scopes simply to avoid planning permissions later. Keep balance and usage permissions separate during review and validation. If the flow does not work as expected, check the S256 setting for public clients, the requested scope list, and where the ext token is stored. Treat any ext token found in frontend code as a configuration issue and correct the integration before continuing.
For a first integration, validate the smallest authorization path before adding more business scopes. After configuration, return to `/docs#docs-oauth` to review the documentation and verify the flow with the corresponding tool. This approach keeps the integration focused on user authorization, required scopes, and app-scoped usage without relying on unverified assumptions.