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