auth-http-api-cloudbase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用该技能

Use this skill whenever you need to call CloudBase Auth via raw HTTP APIs, for example:

Non-Node backends (Go, Python, Java, PHP, etc.)
Integration tests or admin scripts that use curl or language HTTP clients
Gateways or proxies that sit in front of CloudBase and manage tokens themselves

Do not use this skill for:

Frontend Web login with
```
@cloudbase/js-sdk@2.x
```
(use CloudBase Web Auth skill)
Node.js code that uses
```
@cloudbase/node-sdk
```
(use CloudBase Node Auth skill)
Non-auth CloudBase features (database, storage, etc.)

当你需要通过原生HTTP API调用CloudBase Auth时，即可使用该技能，例如：

非Node后端（Go、Python、Java、PHP等）
使用curl或语言原生HTTP客户端的集成测试或管理脚本
部署在CloudBase前端、自行管理令牌的网关或代理

请勿在以下场景使用该技能：

使用
```
@cloudbase/js-sdk@2.x
```
的前端Web登录（请使用CloudBase Web Auth技能）
使用
```
@cloudbase/node-sdk
```
的Node.js代码（请使用CloudBase Node Auth技能）
CloudBase的非认证功能（数据库、存储等）

How to use this skill (for a coding agent)

如何使用该技能（面向编码Agent）

Clarify the scenario
- Confirm this code will call HTTP endpoints directly (not SDKs).
- Ask for:
  - ```
  env
```
  – CloudBase environment ID
- ```
clientId
```
    /
```
clientSecret
```
    – HTTP auth client credentials
- Confirm whether the flow is login/sign-up, anonymous access, token management, or user operations.
Set common variables once
- Use a shared set of shell variables for base URL and headers, then reuse them across scenarios.
Pick a scenario from this file
- For login / sign-up, start with Scenarios 1–3.
- For token lifecycle, use Scenarios 4–6.
- For user info and profile changes, use Scenario 7.
Never invent endpoints or fields
- Treat the URLs and JSON shapes in this file as canonical.
- If you are unsure, consult the HTTP API docs under
```
/source-of-truth/auth/http-api/登录认证接口.info.mdx
```
  and the specific
```
*.api.mdx
```
  files.

明确场景
- 确认代码将直接调用HTTP端点（而非SDK）。
- 需获取以下信息：
  - ```
  env
```
  – CloudBase环境ID
- ```
clientId
```
    /
```
clientSecret
```
    – HTTP认证客户端凭证
- 确认流程类型：登录/注册、匿名访问、令牌管理或用户操作。
一次性设置通用变量
- 为基础URL和请求头设置一组共享的Shell变量，然后在各场景中复用。
从本文档中选择对应场景
- 若为登录/注册场景，从场景1–3开始。
- 若为令牌生命周期管理，使用场景4–6。
- 若为用户信息和资料修改，使用场景7。
切勿自行编造端点或字段
- 请将本文档中的URL和JSON结构视为标准规范。
- 若有疑问，请查阅
```
/source-of-truth/auth/http-api/登录认证接口.info.mdx
```
  下的HTTP API文档及具体的
```
*.api.mdx
```
  文件。

HTTP API basics

HTTP API基础

Base URL pattern

https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/...

Common headers
- ```
x-device-id
```
  – device or client identifier
- ```
x-request-id
```
  – unique request ID for tracing
- ```
Authorization
```
  –
```
Bearer <access_token>
```
  for user endpoints
- Or HTTP basic auth (
```
-u clientId:clientSecret
```
  ) for client-credential style endpoints
Reusable shell variables

bash

env="your-env-id"
deviceID="backend-service-1"
requestID="$(uuidgen || echo manual-request-id)"
clientId="your-client-id"
clientSecret="your-client-secret"
base="https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1"

基础URL格式

https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/...

通用请求头
- ```
x-device-id
```
  – 设备或客户端标识符
- ```
x-request-id
```
  – 用于追踪的唯一请求ID
- ```
Authorization
```
  – 用户端点需使用
```
Bearer <access_token>
```
- 客户端凭证式端点可使用HTTP基础认证（
```
-u clientId:clientSecret
```
  ）
可复用的Shell变量

bash

env="your-env-id"
deviceID="backend-service-1"
requestID="$(uuidgen || echo manual-request-id)"
clientId="your-client-id"
clientSecret="your-client-secret"
base="https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1"

Core concepts (HTTP perspective)

核心概念（HTTP视角）

CloudBase Auth uses JWT access tokens plus refresh tokens.
HTTP login/sign-up endpoints usually return both
```
access_token
```
and
```
refresh_token
```
.
Most user-management endpoints require
```
Authorization: Bearer ${accessToken}
```
.
Verification flows (SMS/email) use separate
```
verification
```
endpoints before sign-up.

CloudBase Auth使用JWT访问令牌和刷新令牌。
HTTP登录/注册端点通常会同时返回
```
access_token
```
和
```
refresh_token
```
。
大多数用户管理端点需要携带
```
Authorization: Bearer ${accessToken}
```
。
验证流程（短信/邮箱）需在注册前调用独立的
```
verification
```
端点。

Scenarios (flat list)

场景列表（扁平化）

Scenario 1: Sign-in with username/password

场景1：用户名/密码登录

bash

curl "${base}/signin" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"username":"test@example.com","password":"your password"}'

Use when the user already has a username (phone/email/username) and password.
Response includes
```
access_token
```
,
```
refresh_token
```
, and user info.

bash

curl "${base}/signin" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"username":"test@example.com","password":"your password"}'

适用于用户已拥有用户名（手机号/邮箱/用户名）和密码的场景。
响应包含
```
access_token
```
、
```
refresh_token
```
和用户信息。

Scenario 2: SMS sign-up with verification code

场景2：短信验证码注册

Send verification code

bash

curl "${base}/verification" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"phone_number":"+86 13800000000"}'

Verify code

bash

curl "${base}/verification/verify" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"verification_code":"000000","verification_id":"<from previous step>"}'

Sign up

bash

curl "${base}/signup" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{
    "phone_number":"+86 13800000000",
    "verification_code":"000000",
    "verification_token":"<from verify>",
    "name":"手机用户",
    "password":"password",
    "username":"username"
  }'

Use this pattern for SMS or email-based registration; adapt fields per docs.

发送验证码

bash

curl "${base}/verification" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"phone_number":"+86 13800000000"}'

验证验证码

bash

curl "${base}/verification/verify" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"verification_code":"000000","verification_id":"<from previous step>"}'

完成注册

bash

curl "${base}/signup" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{
    "phone_number":"+86 13800000000",
    "verification_code":"000000",
    "verification_token":"<from verify>",
    "name":"手机用户",
    "password":"password",
    "username":"username"
  }'

该模式适用于短信或邮箱注册；可根据文档调整字段。

Scenario 3: Anonymous login

场景3：匿名登录

bash

curl "${base}/signin-anonymously" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{}'

Returns tokens for an anonymous user that you can later upgrade via sign-up.

bash

curl "${base}/signin-anonymously" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{}'

返回匿名用户的令牌，后续可通过注册将其升级为正式用户。

Scenario 4: Exchange refresh token for new access token

场景4：使用刷新令牌换取新的访问令牌

bash

curl "${base}/token" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"grant_type":"refresh_token","refresh_token":"<refresh_token>"}'

Use when the frontend or another service sends you a refresh token and you need a fresh access token.

bash

curl "${base}/token" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"grant_type":"refresh_token","refresh_token":"<refresh_token>"}'

当前端或其他服务向你发送刷新令牌，而你需要获取新的访问令牌时使用。

Scenario 5: Introspect and validate a token

场景5：令牌自省与验证

bash

curl "${base}/token/introspect?token=${accessToken}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}"

Use for backend validation of tokens before trusting them.
Response indicates whether the token is active and may include claims.

bash

curl "${base}/token/introspect?token=${accessToken}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}"

适用于后端在信任令牌前对其进行验证。
响应会标明令牌是否有效，并可能包含声明信息。

Scenario 6: Revoke a token (logout)

场景6：吊销令牌（登出）

bash

curl "${base}/revoke" \
  -X POST \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"token":"${accessToken}"}'

Call when logging a user out from the backend or on security events.

bash

curl "${base}/revoke" \
  -X POST \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"token":"${accessToken}"}'

当从后端登出用户或发生安全事件时调用。

Scenario 7: Basic user operations (me, update password, delete)

场景7：基础用户操作（获取自身信息、修改密码、删除账户）

bash

undefined

bash

undefined

Get current user

curl "${base}/user/me"
-H "Authorization: Bearer ${accessToken}"

Change password

curl "${base}/user/password"
-X PATCH
-H "Authorization: Bearer ${accessToken}"
--data-raw '{"old_password":"old","new_password":"new"}'


- Other endpoints:
  - `DELETE ${base}/user/me` – delete current user.
  - `${base}/user/providers` plus bind/unbind APIs – manage third-party accounts.
- Always secure these operations and log only minimal necessary data.

curl "${base}/user/password"
-X PATCH
-H "Authorization: Bearer ${accessToken}"
--data-raw '{"old_password":"old","new_password":"new"}'


- 其他端点：
  - `DELETE ${base}/user/me` – 删除当前用户。
  - `${base}/user/providers`及绑定/解绑API – 管理第三方账户。
- 请始终确保这些操作的安全性，仅记录必要的最少数据。