Create OAuth Application is for third-party developers and covers the standard OAuth 2.0 integration process.

When to use: when your product or tool needs to access a user's CNB resources — for example an IDE plugin reading repository code, or your own platform calling OpenAPI on a user's behalf. Register the application, obtain user authorization, then exchange it for an access ticket.

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; the user is redirected back here after 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:

https://cnb.cool/oauth2/auth?client_id=CLIENTID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE

The parameters for this step are:

• response_type: Authorization type, required, fixed value code
• client_id: Client ID, required
• redirect_uri: Redirect URI, optional; the domain must match the authorized domain submitted during review
• state: Current state of the client; can be any value and will be returned unchanged by the authentication server

If prompted "This link cannot be accessed", it is usually because redirect_uri does not match the authorized domain submitted during review.

GET /oauth2/auth?response_type=code&client_id=<YOUR_CLIENT_ID>&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: cnb.cool

After the user grants authorization, they are redirected to redirect_uri with these parameters:

• code: Authorization code, required. Usually valid for 10 minutes and usable only once, with a one-to-one correspondence to the Client ID and Redirect URI.
• state: Returned unchanged when the request included this parameter.

Example response:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=<YOUR_AUTH_CODE>&state=xyz

2. Get access_token via code

The client requests a token from the authentication server with these 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.

The client authentication method is chosen when the application is registered. Supported values (client_secret_basic is the default):

Value	Description
client_secret_basic	HTTP Basic Authentication, the default
client_secret_post	client_id/client_secret are sent in the request body
private_key_jwt	Private-key-signed JWT assertion; a public key (inline JWK Set or JWKS URL) is required, and client_secret is not sent
none	Public client without authentication, typically used for SPAs or native apps

Authenticating with a JWT assertion

private_key_jwt does not send client_secret; it authenticates with a JWT assertion:

POST /oauth2/token HTTP/1.1
Host: cnb.cool
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<YOUR_AUTH_CODE>
&client_id=<YOUR_CLIENT_ID>
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=<YOUR_CLIENT_ASSERTION_JWT>

client_assertion is an RFC 7523 JWT with the following claims:

• iss: the client ID (client_id)
• sub: the client ID (client_id)
• aud: the token endpoint, i.e. https://cnb.cool/oauth2/token
• exp: expiration time, must be in the future
• jti: unique assertion identifier, used for replay protection

Signing algorithm: private_key_jwt signs with your private key using an asymmetric algorithm such as RS256; the corresponding public key must be provided at registration.

For private_key_jwt, provide the public key in one of two ways:

• Inline JWK Set: submit the public key as a JWK Set, e.g. {"keys":[{"kty":"RSA","n":"...","e":"AQAB","kid":"...","use":"sig","alg":"RS256"}]}
• JWKS URL: provide a publicly reachable JWKS endpoint (jwks_uri) from which the platform fetches the public key. The URL must start with https://; plain HTTP would let a man-in-the-middle swap the public key, so the platform rejects it

POST /oauth2/token HTTP/1.1
Host: cnb.cool
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<YOUR_AUTH_CODE>&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

The authentication server returns these 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/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"<YOUR_ACCESS_TOKEN>",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"<YOUR_REFRESH_TOKEN>"
}

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

POST /oauth2/token HTTP/1.1
Host: cnb.cool
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<YOUR_REFRESH_TOKEN>

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

Authentication works the same way as in Get access_token via code.

POST /oauth2/revoke HTTP/1.1
Host: cnb.cool
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

token=<YOUR_ACCESS_TOKEN>

The authentication server responds as follows:

• 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/1.1 200 OK

Example response on authentication failure:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": "invalid_client",
    "error_description": "Client authentication failed"
}

Local Device Authorization

For tools that run locally, use the OAuth 2.0 Device Authorization Grant (RFC 8628): the user authorizes once in a browser, and the tool receives an access token.

CNB CLI has this flow built in — just run cnb login. For integration details and usage, see CNB CLI.

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	Access an org's sub-organizations, repos, registries, missions, and usage/quota; create repos and missions
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

Previous pageHow to Use OAuth Authorization