---
url: /en/oauth/developer.md
---
This document aims to provide third-party developers with a standardized OAuth 2.0 application integration process, supporting application registration, user authorization (personal/resource level), 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 we will contact you to discuss the specific plan for creating your OAuth application.

### Basic Application Information

| Application Info | Required | Field Description |
| :--------   | ---- |  :----- |
| Application Name   | Yes  | Displayed to users during authorization and on the user authorization management page; max 50 characters. |
| Application Logo  | Yes  | Image size must not exceed 1MB. |
| Application Description   | No | Max 350 characters. |
| Official Website   | Yes  | Max 128 characters. |
| Redirect URL   | Yes  | Redirect URI, used for redirection after OAuth authorization.  |
| Supported Authorization Scopes   | Yes  | Communicated during the application creation plan, e.g., `repo-code:r`, `account-profile:r`, etc. Must be predefined. Applications should only request necessary permission scopes, and the CNB platform will evaluate the reasonableness of the authorization scope during review. |
| Authorization Resource Scope   | Yes  | All permissions of the current account / All public resources of the current account / 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, carrying the corresponding parameters, to request their CNB identity.
3. After the user agrees, CNB will launch the application or redirect to the third-party website, carrying the authorization temporary ticket `code` parameter.
4. Exchange for an `access_token` via API using the `code` parameter plus ClientID and ClientSecret, etc.
5. Invoke interfaces using the `access_token` to obtain basic user data resources or help users perform basic operations.

### 1. Initiate Authorization Request

Third-party websites/apps can initiate authorized login by opening the following link in a browser:

```text
https://cnb.share.ralphlauren.cn/oauth2/auth?client_id=CLIENTID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE
```

If prompted "The link cannot be accessed", please check if parameters are filled incorrectly, such as the domain of `redirect_uri` not matching the authorization domain filled during review.

The following are the parameters required for the above steps:

* `response_type`: Indicates the authorization type, required, fixed value is `code`.
* `client_id`: Indicates the client ID, required.
* `redirect_uri`: Indicates the redirect URI, optional.
* `state`: Indicates the current state of the client, can be any value; the authentication server will return this value unchanged.

```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: cnb.share.ralphlauren.cn
```

The server responds to the client with a URI containing the following parameters:

* `code`: Indicates the authorization code, required. The validity period should be short, usually set to 10 minutes. The client can only use this code once; otherwise, it will be rejected by the authorization server. This code has a one-to-one correspondence with the `Client_ID` and `Redirect URI`.
* `state`: If the client request included this parameter, the authentication server response must include this parameter exactly as is.

After the user grants authorization, they will be redirected to the `redirect_uri` URL, carrying the `code` and `state` parameters. Example below:

```http
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
```

### 2. Get access\_token via code

The HTTP request from the client to the authentication server to apply for a token contains the following parameters:

* `grant_type`: Indicates the authorization mode, required, fixed value is `authorization_code`.
* `code`: The authorization code obtained in the previous step, required.
* `redirect_uri`: Redirect URI, optional, must match the value in the first step's code request.

`client_id`/`client_secret` can also be sent to the server in the Authorization field of the request header in the form of Base64 encoding via HTTP Basic Authentication.

```http
POST /oauth2/token HTTP/1.1
Host: cnb.share.ralphlauren.cn
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
```

The HTTP response sent by the authentication server includes the following parameters:

* `access_token`: Indicates the access token, 8-hour validity, required.
* `token_type`: Indicates the token type, case-insensitive, required, can be `bearer` type or `mac` type.
* `expires_in`: Indicates expiration time in seconds. If omitted, the expiration must be set via other means.
* `refresh_token`: Indicates the update token, used to get the next access token, optional.
* `scope`: Indicates permission scope; if consistent with the client's requested scope, this can be omitted.

```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` is the credential for calling authorization interfaces. Since the validity period of the `access_token` is short (8 hours), the `refresh_token` can be used to refresh it when the `access_token` times out. Every time a refresh token is used, a new token and refresh token will be returned. The old token and refresh token can still be used within a grace period (5 minutes). Please keep the user's relevant tokens securely.

The `refresh_token` has a longer validity period (180 days). When the `refresh_token` expires, the user needs to re-authorize.

The client issues an HTTP request to update the token, containing the following parameters:

* `grant_type`: Indicates the authorization mode, fixed value is `refresh_token`, required.
* `refresh_token`: The refresh token received earlier, required.

```http
POST /oauth2/token HTTP/1.1
Host: cnb.share.ralphlauren.cn
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
```

The return example is the same as `access_token`.

### 4. Revoke Token

When a user logs out or an application needs to proactively invalidate a token, you can call the revoke endpoint to revoke an `access_token` or `refresh_token`. Once revoked, the token is immediately invalidated and can no longer be used for API calls.

The client issues an HTTP request to revoke a token, containing the following parameters:

* `token`: The token to be revoked (`access_token` or `refresh_token`), required.
* `client_id`: The client ID, optional; can also be passed via HTTP Basic Authentication.
* `client_secret`: The client secret, optional; can also be passed via HTTP Basic Authentication.

`client_id`/`client_secret` can also be sent to the server in the Authorization field of the request header in the form of Base64 encoding via HTTP Basic Authentication.

```http
POST /oauth2/revoke HTTP/1.1
Host: cnb.share.ralphlauren.cn
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

token=2YotnFZFEjr1zCsicMWpAA
```

The HTTP response sent by the authentication server:

* On successful revocation, returns HTTP `200`.
* If the provided token is invalid or already expired, the server also returns HTTP `200` (compliant with RFC 7009).
* If `client_id`/`client_secret` authentication fails, the server returns 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 in ISSUEs, and pull requests |
| repo-contents | Read-only / Read-write| Access files, branches, commit records, tags, versions |
| repo-commit-status | Read-only / Read-write | Access pipeline execution status, badges, commit metadata |
| repo-cnb-trigger | Read-only / Read-write | Query, delete, trigger, execute Cloud Native Build, start Cloud Native Development |
| repo-cnb-history | Read-only | Query pipeline build history |
| repo-cnb-detail | Read-only / Read-write | Query or delete Cloud Native Development space |
| repo-basic-info | Read-only | Access basic repository information, such as repository name, description, language, license, etc. |
| repo-manage | Read-only / Read-write | Access repository members, repository settings |
| repo-delete | Read-write | Delete repository |
| repo-security | Read-only | Access repository security module data |
| registry-package | Read-only / Read-write | Access artifacts |
| registry-package-delete | Read-write | Delete artifacts |
| registry-manage | Read-only / Read-write | Access artifact registry members, artifact registry settings |
| registry-delete | Read-write | Delete artifact registry |
| account-profile | Read-only / Read-write | Access user profile |
| account-email | Read-only / Read-write | Query user verified email |
| account-engage | Read-only / Read-write | Access repositories followed by the user, followers, following, Cloud Native Development environments, etc. |
| group-resource | Read-only / Read-write | Access sub-organizations, repositories |
| group-manage | Read-only / Read-write | Access organization members, repository wall, organization settings |
| group-delete | Read-only / Read-write | Delete organization |
| mission-delete | Read-only / Read-write | Delete mission set |
| mission-manage | Read-only / Read-write | Access mission set |