auth-http-api-cloudbase

name	auth-http-api-cloudbase
description	Use when you need to implement CloudBase Auth v2 over raw HTTP endpoints (login/signup, tokens, user operations) from backends or scripts that are not using the Web or Node SDKs.
alwaysApply	false

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

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":"[e-mail]","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":"[phone]"}'

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

3. Sign up

curl "${base}/signup" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{
    "phone_number":"[phone]",
    "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.