auth-http-api-cloudbase

When to use this skill

• 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

• 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.)

How to use this skill (for a coding agent)

1. 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.
2. Set common variables once
   • Use a shared set of shell variables for base URL and headers, then reuse them across scenarios.
3. 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.
4. 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 API basics

• 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

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)

• 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.

Scenarios (flat list)

Scenario 1: Sign-in with username/password

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.

Scenario 2: SMS sign-up with verification code

1. Send verification code

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

1. Verify code

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>"}'

1. Sign up

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.

Scenario 3: Anonymous login

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.

Scenario 4: Exchange refresh token for new access token

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.

Scenario 5: Introspect and validate a token

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.

Scenario 6: Revoke a token (logout)

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.

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

# 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.