平台令牌

2373 字约 8 分钟

概述

平台令牌提供给外部第三方服务使用，支持第三方服务通过调用换票接口来获得 云原生构建 OpenAPI 的临时访问票据。

平台令牌申请

前往 admin 管理平台，为第三方服务创建平台令牌，得到 name 和 secret_key。

服务地址

服务请求地址为 3rd.cnb.share.ralphlauren.cn。

接口

CNB 提供了两种方式的换票接口，以满足不同需求:

基于用户名的换票

接口地址: /platform-token/-/user/{username}
接口方法: "POST"
系统授权: system-token:rw
功能描述: 此接口用于换取指定 {username} 用户的个人令牌。
参数:
- expire: 可选参数，令牌有效期，支持1m~24h

基于用户ID的换票

接口地址: /platform-token/-/userid/{userid}
接口方法: "POST"
系统授权: system-token:rw
功能描述: 此接口用于换取指定 {userid} 用户的个人令牌。
参数:
- expire: 可选参数，令牌有效期，支持1m~24h

基于openid的换票

接口地址: /platform-token/-/openid/{openid}
接口方法: "POST"
系统授权: system-token:rw
功能描述: 此接口用于换取指定 {openid} 用户的个人令牌。
参数:
- user_type: 可选参数，用户类型，对应关系如下:
  - 0: 微信用户
  - 1: oauth 授权用户
  - 2: 测试用户
  - 3: 助手用户
  - 4: ioa 授权用户
    默认值为 1.
- expire: 可选参数，令牌有效期，支持1m~24h

基于仓库全路径的换票

接口地址: /platform-token/-/repo/{repo-path}
接口方法: "POST"
系统授权: system-token:rw
功能描述: 此接口将随机选择 {repo-path} 仓库的某位负责人用户，并换取该负责人用户的个人令牌。
参数:
- expire: 可选参数，令牌有效期，支持1m~24h

基于组织全路径的换票

接口地址: /platform-token/-/organization/{organization-path}
接口方法: "POST"
系统授权: system-token:rw
功能描述: 此接口将随机选择 {organization-path} 组织的某位负责人用户，并换取该负责人用户的个人令牌。
参数:
- expire: 可选参数，令牌有效期，支持1m~24h

列出所有根组织

接口地址: /platform-token/-/organization
接口方法: "GET"
系统授权: system-search:r
功能描述: 遍历并列出所有根组织信息。
参数:
- page: 页码，从1开始
- page_size: 每页数量
- search: 根组织名称，只支持全匹配

查找资源ID对应的对象信息

接口地址: /platform-token/-/resolve/{type:string}
接口方法: "POST"
系统授权: system-search:r
功能描述: 查找资源ID对应的对象信息。
参数:
- type: 类型 organization/repo/mission/registry/user
- body: 请求 ID 列表
```
{
  "id": ["123"]
}
```

查找绑定码或认证手机号码对应的对象信息

接口地址: /platform-token/-/bind/user
接口方法: "POST"
系统授权: system-bind:r
功能描述: 查找绑定码或认证手机号码对应的对象信息
参数:
- body: 请求 json 内容
```
{
  "type": "code",
  "user": "someone",
  "code": "123456"
}
```
  - type: 码类型，支持 code 绑定码, phone 手机号码
  - code: 码内容，如 123456, 或者 1581xxx
  - user: CNB 账户用户名

返回: 用户信息

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

绑定用户

接口地址: /platform-token/-/bind/user/{openid:string}
接口方法: "POST"
系统授权: system-bind:rw
功能描述: 绑定用户
参数:
- openid: 第三方平台用户唯一ID
- body: 请求 json 内容
```
{
  "type": "code",
  "code": "123456",
  "user": "someone",
  "metadata": {
    "name": "hello"
  }
}
```
  - type: 码类型，支持 code 绑定码, phone 手机号码
  - code: 码内容，如 123456, 或者 1581xxx
  - user: CNB 账户用户名
  - metadata: 自定义元数据

返回: 用户信息

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

批量解除用户绑定

接口地址: /platform-token/-/unbind/user/{username:string or userid:string}
接口方法: "POST"
系统授权: system-bind:rw
功能描述: 解除该用户在此平台上的所有绑定记录

解除用户绑定

接口地址: /platform-token/-/unbind/user/{username:string or userid:string}/{openid:string}
接口方法: "POST"
系统授权: system-bind:rw
功能描述: 解除该用户在此平台上的某一条绑定记录

锁定用户

接口地址: /platform-token/-/lock/user/{username:string}
接口方法: "POST"
系统授权: system-lock:rw
功能描述: 锁定指定 {username} 的用户
参数:
- body: 请求 json 内容
```
{
  "lock_duration": "10"
}
```
  - lock_duration: 锁定天数

解锁用户

接口地址: /platform-token/-/unlock/user/{username:string}
接口方法: "POST"
系统授权: system-lock:rw
功能描述: 解锁指定 {username} 的用户

创建新用户

接口地址: /platform-token/-/user/create/{openid:string}
接口方法: "POST"
系统授权: system-user:rw
功能描述: 新建指定 {openid} 的 cnb 用户

参数:

body: 请求 json 内容

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

name: 用户名
nick: 用户昵称
email: 用户邮箱

更新用户信息

接口地址: /platform-token/-/user/update/{openid:string}
接口方法: "POST"
系统授权: system-user:rw
功能描述: 更新指定 {openid} 的 cnb 用户的信息

参数:

body: 请求 json 内容

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

name: 用户名
nick: 用户昵称
email: 用户邮箱

基于邮箱查询用户信息

接口地址: /platform-token/-/user
接口方法: "POST"
系统授权: system-userinfo:r
功能描述: 基于邮箱查询用户信息

参数:

body: 请求 email 邮箱列表

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

资源绑定接口

绑定资源

接口地址: /platform-token/-/bind/resource
接口方法: "POST"
系统授权: system-bind:rw
功能描述: 将第三方平台的实例与 CNB 资源进行绑定
参数:
- body: 请求 json 内容
```
{
  "openid": "third-party-instance-id",
  "slug": "organization/repo",
  "code": "123456",
  "metadata": {
    "key": "value"
  }
}
```
  - openid: 第三方平台实例唯一ID
  - slug: CNB 资源路径（如：组织/仓库）
  - code: 绑定码
  - metadata: 可选，绑定的扩展信息

获取资源绑定信息

接口地址: /platform-token/-/bind/resource
接口方法: "GET"
系统授权: system-bind:r
功能描述: 获取资源的绑定信息
参数:
- slug: 可选参数，过滤绑定的资源路径
- openid: 可选参数，过滤绑定的实例 openID

返回: 资源绑定信息

{
  "data": [
    {
      "slug": "organization/repo",
      "openid": "third-party-instance-id",
      "metadata": "{\"key\":\"value\"}",
      "created_at": "2026-03-10T10:00:00Z",
      "updated_at": "2026-03-10T10:00:00Z"
    }
  ],
  "repository": {
    "id": "123456",
    "name": "repo",
    "path": "organization/repo"
  }
}

解绑资源

接口地址: /platform-token/-/bind/resource
接口方法: "DELETE"
系统授权: system-bind:rw
功能描述: 解除第三方平台实例与 CNB 资源的绑定
参数:
- slug: 可选参数，过滤绑定的资源路径
- openid: 可选参数，过滤绑定的实例 openID
- 注意: 如果只提供 openid，则解除该实例的所有绑定；如果同时提供 slug 和 openid，则只解除特定资源的绑定

部署令牌接口

平台令牌绑定资源后，可以为绑定的实例创建和管理部署令牌。部署令牌用于访问绑定的 CNB 资源（如代码仓库），每个实例的部署令牌通过唯一的密钥标识（key）进行管理。

创建部署令牌

接口地址: /platform-token/-/deploy-keys/{openid}/{key}
接口方法: "POST"
系统授权: 继承平台令牌的权限范围
功能描述: 为已绑定的第三方平台实例创建部署令牌
路径参数:
- openid: 第三方平台实例唯一ID（必须已完成资源绑定）
- key: 密钥标识，用于标识和管理该实例的部署令牌（同一 openid + key 组合唯一）
参数:
- body: 请求 json 内容
```
{
  "slug": "organization/repo",
  "description": "用于 CI/CD 的部署令牌",
  "scope": "registry-package:r",
  "metadata": {
    "environment": "production"
  }
}
```
  - slug: CNB 资源路径，必须是已绑定的资源
  - description: 可选，令牌描述信息
  - scope: 可选，令牌的权限范围
  - metadata: 可选，令牌的扩展信息
返回: 创建成功的令牌
```
{
  "token": "dk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```
注意: 令牌只在创建时返回一次，请妥善保存

删除部署令牌

接口地址: /platform-token/-/deploy-keys/{openid}/{key}
接口方法: "DELETE"
系统授权: 继承平台令牌的权限范围
功能描述: 删除指定的部署令牌
路径参数:
- openid: 第三方平台实例唯一ID
- key: 密钥标识
返回: HTTP 204 No Content

请根据实际需求选择合适的接口进行操作。

Header 头信息

Authorization，string类型，HTTP 标准身份认证头部字段，使用标准 jwt 来计算签名，格式为: Bearer ${token}。

go jwt 加密示例如下

import (
 "fmt"
 "time"

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

// Claims 认证请求所需的参数
type Claims struct {
  JWTPayload // 用户自定义 jwt payload 结构
  jwt.RegisteredClaims
}

// Generate 签名编码
func Generate(payload JWTPayload, name, secretKey string) (string, error) {
  claims := Claims{
    payload,
    jwt.RegisteredClaims{
      Issuer:   name, // 平台令牌 name
      IssuedAt: jwt.NewNumericDate(time.Now().UTC()), // 当前utc时间
    },
  }
  token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
  return token.SignedString([]byte(secretKey))
}

python jwt 加密示例如下

from datetime import datetime, timezone
import jwt

class JWTPayload:
  """JWT payload 自定义结构"""
  pass

def generate(payload: JWTPayload, name: str, secret_key: str) -> str:
claims = {
    # 标准声明
    "iss": name,  # Issuer - 平台令牌 name
    "iat": datetime.now(timezone.utc),  # IssuedAt - 当前 UTC 时间

    # 可以在这里添加自定义 payload 字段
    # 如果 payload 有属性，可以通过 vars(payload) 或 payload.__dict__ 获取
}

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

jwt 更详细的介绍请参考官方文档。

需要注意的是, 请将 jwt Claims 的 issueAt 字段赋值为当前 UNIX 时间戳，记录发起 API 请求的时间。 注意: 如果该时间与服务器时间相差超过2分钟，调用接口会返回签名过期错误。

接口返回

换票接口请求成功后，会返回24小时有效的临时票据，可以使用该票据调用 OpenAPI 接口。

OpenAPI 接口详情请参照云原生构建 OpenAPI 接口文档。

请求示例

curl 请求示例

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

返回结果示例

{ "token": "bHaDbC6esm88116aZOGDbpH26fL" }