--- url: /en/oauth/developer.md description: > Guides third-party developers through the CNB OAuth 2.0 integration process, covering application registration, user authorization flows, temporary ticket issuance, and API access control. --- This document describes the standard OAuth 2.0 application integration process, covering application registration, user authorization, temporary ticket issuance, and API access control. ## Preparation: Apply for OAuth Application Registration ### App Information Registration Currently, applications require approval from CNB administrators before they can be published. Please submit your application details to an administrator, and they will contact you to discuss the specific creation plan. ### Basic Application Information | Application Info | Required | Description | | :------------------------- | :------- | :------------------------------------------------------- | | Application Name | Yes | Displayed during authorization; max 50 characters | | Application Logo | Yes | Image size must not exceed 1 MB | | Application Description | No | Max 350 characters | | Official Website | Yes | Max 128 characters | | Redirect URL | Yes | Redirect URI, used for redirection after OAuth auth | | Authorization Scopes | Yes | Only request necessary permissions; reviewed by platform | | Authorization Resource Scope | Yes | All resources / All public resources / Specified resources | ## Authorization Process The authorization process for users within the application is as follows: 1. The user initiates a CNB authorization request within the application 2. Redirect the user to CNB's authorization page with the corresponding parameters 3. After the user agrees, CNB redirects to the application's callback URL with the authorization code `code` 4. Exchange for an `access_token` via API using `code`, `ClientID`, and `ClientSecret` 5. Use the `access_token` to call APIs for retrieving user data or performing operations ### 1. Initiate Authorization Request Third-party websites/apps can initiate authorized login by opening the following link in a browser: ```text https://cnbprod.alpha.qq.com/oauth2/auth?client_id=CLIENTID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE ``` If prompted "This link cannot be accessed", please check if the parameters are correct, e.g., whether the domain of `redirect_uri` matches the authorized domain submitted during review. The following parameters are required: * `response_type`: Authorization type, required, fixed value `code` * `client_id`: Client ID, required * `redirect_uri`: Redirect URI, optional * `state`: Current state of the client; can be any value and will be returned unchanged by the authentication server ```http GET /oauth2/auth?response_type=code&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 Host: cnbprod.alpha.qq.com ``` The server returns a URI containing the following parameters: * `code`: Authorization code, required. Usually valid for 10 minutes and can only be used once. Has a one-to-one correspondence with the Client ID and Redirect URI. * `state`: If the client request included this parameter, the response must include the same value. After the user grants authorization, they will be redirected to the `redirect_uri` URL with the `code` and `state` parameters. Example: ```http HTTP/1.1 302 Found Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz ``` ### 2. Get access\_token via code The client requests a token from the authentication server with the following parameters: * `grant_type`: Authorization mode, required, fixed value `authorization_code` * `code`: Authorization code obtained in the previous step, required * `redirect_uri`: Redirect URI, optional, must match the value from the first step `client_id`/`client_secret` can also be sent in the `Authorization` header via HTTP Basic Authentication in Base64 encoding. ```http POST /oauth2/token HTTP/1.1 Host: cnbprod.alpha.qq.com Authorization: Basic Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb ``` The authentication server returns the following parameters: * `access_token`: Access token, 8-hour validity, required * `token_type`: Token type, case-insensitive, required, can be `bearer` or `mac` * `expires_in`: Expiration time in seconds. If omitted, expiration must be set via other means * `refresh_token`: Refresh token, used to obtain the next access token, optional * `scope`: Permission scope; can be omitted if consistent with the requested scope ```http HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"bearer", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" } ``` ### 3. Update Token via refresh\_token The `access_token` has a short validity period (8 hours). When it expires, use the `refresh_token` to refresh it. A new token pair is returned after each refresh, and old tokens remain usable during a grace period (5 minutes). The `refresh_token` has a longer validity period (180 days). When it expires, the user must re-authorize. Request parameters: * `grant_type`: Authorization mode, required, fixed value `refresh_token` * `refresh_token`: The refresh token received earlier, required ```http POST /oauth2/token HTTP/1.1 Host: cnbprod.alpha.qq.com Authorization: Basic Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA ``` The return format is the same as for `access_token`. ### 4. Revoke Token When a user logs out or the application needs to invalidate a token, call the revoke endpoint to revoke an `access_token` or `refresh_token`. The token becomes invalid immediately. Request parameters: * `token`: The token to be revoked (`access_token` or `refresh_token`), required * `client_id`: Client ID, optional; can also be passed via HTTP Basic Authentication * `client_secret`: Client secret, optional; can also be passed via HTTP Basic Authentication `client_id`/`client_secret` can also be sent in the `Authorization` header via HTTP Basic Authentication in Base64 encoding. ```http POST /oauth2/revoke HTTP/1.1 Host: cnbprod.alpha.qq.com Authorization: Basic Content-Type: application/x-www-form-urlencoded token=2YotnFZFEjr1zCsicMWpAA ``` The authentication server response: * Successful revocation: HTTP `200` * Invalid or expired token: Also returns HTTP `200` (compliant with RFC 7009) * `client_id`/`client_secret` authentication failure: HTTP `401` with error details in the response body ```http HTTP/1.1 200 OK ``` Example response on authentication failure: ```http HTTP/1.1 401 Unauthorized Content-Type: application/json { "error": "invalid_client", "error_description": "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)." } ``` ## Authorization Scopes | Action Permission | Permission Type | Description | | :--------------------- | :-------------------- | :-------------------------------------------------- | | repo-code | Read-only / Read-write | Access code repository via Git commands | | repo-pr | Read-only / Read-write | Access pull requests | | repo-issue | Read-only / Read-write | Access issues | | repo-notes | Read-only / Read-write | Access comments on issues and pull requests | | repo-release | Read-only / Read-write | Access tags, releases | | repo-commit-status | Read-only / Read-write | Access pipeline status, badges, commit metadata | | repo-cnb-trigger | Read-only / Read-write | Query, trigger, execute Cloud Native Build / Dev | | repo-cnb-history | Read-only | Query pipeline build history | | repo-cnb-detail | Read-only / Read-write | Query or delete Cloud Native Dev spaces | | repo-basic-info | Read-only | Basic repo info (name, description, language, etc.) | | repo-manage | Read-only / Read-write | Repo members and settings | | repo-delete | Read-write | Delete repository | | repo-security | Read-only | Repo security module data | | registry-package | Read-only / Read-write | Access artifacts | | registry-package-delete | Read-write | Delete artifacts | | registry-security | Read-only | Package security, license, and SBOM data | | registry-manage | Read-only / Read-write | Registry members and settings | | registry-delete | Read-write | Delete artifact registry | | account-profile | Read-only / Read-write | User profile | | account-email | Read-only / Read-write | User verified email | | account-engage | Read-only / Read-write | Followed repos, followers, CND environments, etc. | | group-resource | Read-only / Read-write | Sub-organizations and repositories | | group-manage | Read-only / Read-write | Org members, repo wall, and org settings | | group-delete | Read-write | Delete organization | | mission-delete | Read-write | Delete mission set | | mission-manage | Read-only / Read-write | Access mission set |