---
url: /en/paas/platform-token.md
---
## Overview

The Platform Token is provided for external third-party services to use, allowing them to obtain temporary access tokens for the `Cloud Native Build` OpenAPI by calling the token exchange interface.

## Platform Token Application

Go to the Admin Management Platform to create a Platform Token for third-party services, obtaining **name** and **secret\_key**.

## Service Address

The service request address is `3rd.cnb.share.ralphlauren.cn`.

## API

CNB provides two types of token exchange interfaces to meet different needs:

### Token Exchange by Username

* API Address: `/platform-token/-/user/{username}`
* Method: "POST"
* SystemScope: system-token:rw
* Description: This interface is used to exchange a personal token for the specified {username} user.
* Parameters:
  * expire: Optional parameter, token validity period, supports 1m~24h

### Token Exchange by User ID

* API Address: `/platform-token/-/userid/{userid}`
* Method: "POST"
* SystemScope: system-token:rw
* Description: This interface is used to exchange a personal token for the specified {userid} user.
* Parameters:
  * expire: Optional parameter, token validity period, supports 1m~24h

### Token Exchange by OpenID

* API Address: `/platform-token/-/openid/{openid}`
* Method: "POST"
* SystemScope: system-token:rw
* Description: This interface is used to exchange a personal token for the specified {openid} user.
* Parameters:
  * user\_type: Optional parameter. User type mapping:
    * `0`: WeChat user
    * `1`: OAuth user
    * `2`: Test user
    * `3`: Assistant user
    * `4`: IOA authorized user\
      Default is `1`.
  * expire: Optional parameter. Token validity period, supports 1m~24h

### Token Exchange by Repository Path

* API Address: `/platform-token/-/repo/{repo-path}`
* Method: "POST"
* SystemScope: system-token:rw
* Description: This interface randomly selects a responsible user from the {repo-path} repository and exchanges a personal token for that user.
* Parameters:
  * expire: Optional parameter, token validity period, supports 1m~24h

### Token Exchange by Organization Path

* API Address: `/platform-token/-/organization/{organization-path}`
* Method: "POST"
* SystemScope: system-token:rw
* Description: This interface randomly selects a responsible user from the {organization-path} organization and exchanges a personal token for that user.
* Parameters:
  * expire: Optional parameter, token validity period, supports 1m~24h

### List All Root Organizations

* API Address: `/platform-token/-/organization`
* Method: "GET"
* SystemScope: system-search:r
* Description: Traverse and list all root organization information.
* Parameters:
  * page: Page number, starting from 1
  * page\_size: Number of items per page
  * search: Root organization name, supports exact match only

### Resolve Object Information by Resource ID

* API Address: `/platform-token/-/resolve/{type:string}`
* Method: "POST"
* SystemScope: system-search:r
* Description: Resolve object information by resource ID.
* Parameters:
  * type: Type (organization/repo/mission/registry/user)
  * body: Request ID list

    ```json
    {
      "id": ["123"]
    }
    ```

### Resolve Object Information by Binding Code or Phone Number

* API Address: `/platform-token/-/bind/user`
* Method: "POST"
* SystemScope: system-bind:r
* Description: Resolve object information by binding code or authenticated phone number.
* Parameters:
  * body: Request JSON content

    ```json
    {
      "type": "code",
      "user": "someone",
      "code": "123456"
    }
    ```

    * type: Code type, supports `code` (binding code) or `phone` (phone number)
    * code: Code content, e.g., 123456 or 1581xxx
    * user: CNB account username
* Response: User information

  ```json
  {
    "id": "1293243433212",
    "username": "someone"
  }
  ```

### Bind User

* API Address: `/platform-token/-/bind/user/{openid:string}`
* Method: "POST"
* SystemScope: system-bind:rw
* Description: Bind a user.
* Parameters:
  * openid: Unique ID of the third-party platform user
  * body: Request JSON content

    ```json
    {
      "type": "code",
      "code": "123456",
      "user": "someone",
      "metadata": {
        "name": "hello"
      }
    }
    ```

    * type: Code type, supports `code` (binding code) or `phone` (phone number)
    * code: Code content, e.g., 123456 or 1581xxx
    * user: CNB account username
    * metadata: Custom metadata
* Response: User information

  ```json
  {
    "id": "1293243433212",
    "username": "someone"
  }
  ```

### Batch Unbind Users

* API Address: `/platform-token/-/unbind/user/{username:string or userid:string}`
* Method: "POST"
* SystemScope: system-bind:rw
* Description: Unbind all binding records of the user on this platform.

### Unbind User

* API Address: `/platform-token/-/unbind/user/{username:string or userid:string}/{openid:string}`
* Method: "POST"
* SystemScope: system-bind:rw
* Description: Unbind a specific binding record of the user on this platform.

### Lock User

* API Address: `/platform-token/-/lock/user/{username:string}`
* Method: "POST"
* SystemScope: system-lock:rw
* Description: Lock the specified {username} user
* Parameters:
  * body: Request JSON content

    ```json
    {
      "lock_duration": "10"
    }
    ```

    * lock\_duration: Lock duration in days

### Unlock User

* API Address: `/platform-token/-/unlock/user/{username:string}`
* Method: "POST"
* SystemScope: system-lock:rw
* Description: Unlock the specified {username} user

### Create New User

* API Address: `/platform-token/-/user/create/{openid:string}`
* Method: "POST"
* SystemScope: system-user:rw
* Description: Create a new CNB user with specified {openid}
* Parameters:
  * body: Request JSON content

    ```json
    {
      "name": "someone",
      "nick": "someone",
      "email": "someone@cnb.com"
    }
    ```

    * name: Username
    * nick: User nickname
    * email: User email

### Update User Information

* API Address: `/platform-token/-/user/update/{openid:string}`
* Method: "POST"
* SystemScope: system-user:rw
* Description: Update information for the specified {openid} CNB user
* Parameters:
  * body: Request JSON content

    ```json
    {
      "name": "someone",
      "nick": "someone",
      "email": "someone@cnb.com"
    }
    ```

    * name: Username
    * nick: User nickname
    * email: User email

### Query User Information by Email

* API Address: `/platform-token/-/user`
* Method: "POST"
* SystemScope: system-userinfo:r
* Description: Query user information based on email addresses
* Parameters:
  * body: Request email list

    ```json
    {
      "emails": ["test1@tencent.com", "test2@tencent.com"]
    }
    ```

Choose the appropriate API based on your needs.

## Header Information

* `Authorization`, string type, standard HTTP authentication header field, using standard JWT for signature calculation. Format: Bearer ${token}.

  Example of JWT encryption in Go:

  ```go
  import (
   "fmt"
   "time"

   "github.com/golang-jwt/jwt/v5"
  )

  // Claims Required parameters for authentication requests
  type Claims struct {
    JWTPayload // Custom JWT payload structure
    jwt.RegisteredClaims
  }

  // Generate Signature encoding
  func Generate(payload JWTPayload, name, secretKey string) (string, error) {
    claims := Claims{
      payload,
      jwt.RegisteredClaims{
        Issuer:   name, // Platform Token name
        IssuedAt: jwt.NewNumericDate(time.Now().UTC()), // Current UTC time
      },
    }
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString([]byte(secretKey))
  }
  ```

  Example of JWT encryption in Python:

  ```python
  from datetime import datetime, timezone
  import jwt

  class JWTPayload:
    """Custom JWT payload structure"""
    pass

  def generate(payload: JWTPayload, name: str, secret_key: str) -> str:
  claims = {
      "iss": name,  # Issuer - Platform Token name
      "iat": datetime.now(timezone.utc),  # IssuedAt - Current UTC time

  # You can add custom payload fields here
  # If payload has attributes, you can access them via vars(payload) or payload.__dict__
  }

  token = jwt.encode(claims, secret_key, algorithm="HS256")
  return token
  ```

  For more details on JWT, refer to the official documentation.

  Note: Assign the **issueAt** field of **jwt Claims** to the current UNIX timestamp, recording the time of the API request.
  **Note: If this time differs from the server time by more than 2 minutes, the interface will return a signature expiration error.**

## API Response

After a successful token exchange request, a **24-hour** valid temporary token will be returned, which can be used to call OpenAPI interfaces.

For details on OpenAPI interfaces, refer to the [Cloud Native Build OpenAPI Documentation](https://api.cnb.share.ralphlauren.cn).

## Request Example

curl request example:

```bash
curl -X POST 3rd.cnb.share.ralphlauren.cn/platform-token/-/user/someone \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiIiwic2NvcGUiO"
```

Response example:

```json
{ "token": "bHaDbC6esm88116aZOGDbpH26fL" }
```