SSO
Purpose
Use this flow when your external platform needs to exchange an already-authenticated UC mobile user into an SSO token pair.
This SSO flow has 3 stages:
- the mobile app calls UC with a normal bearer token to issue a one-time ticket
- your platform exchanges that ticket using signed server-to-server headers
- your platform refreshes the SSO-issued token pair with the same signed-header scheme
Who Calls What
| Step | Caller | Route | Purpose |
|---|---|---|---|
| 1 | Mobile app | GET /api/v2/sso/ticket | Ask UC for a one-time ticket for the already-authenticated user |
| 2 | Your platform backend | POST /api/v2/sso/verify | Exchange that ticket for an UC access_token and refresh_token |
| 3 | Your platform backend | POST /api/v2/sso/refresh | Refresh the SSO-issued token pair later |
Important
- The mobile app only needs to call the ticket endpoint
verifyandrefreshare intended for backend-to-backend integration- The signed-header rule below applies to
verifyandrefresh, not to the ticket endpoint
Flow Summary
Step 1. Issue a one-time ticketGET /api/v2/sso/ticket
Step 2. Exchange that ticket for tokensPOST /api/v2/sso/verify
Step 3. Refresh the SSO-issued token pairPOST /api/v2/sso/refresh
Shared SSO Signature Rule
/api/v2/sso/verify and /api/v2/sso/refresh both use the same signed-header pattern.
Required headers
| Header | Required | Meaning |
|---|---|---|
X-App-Id | Yes | Agent UUID |
X-Timestamp | Yes | Current Unix timestamp in seconds |
X-Nonce | Yes | Unique random value for replay protection |
X-Signature | Yes | Base64 HMAC-SHA256 signature |
How to build the signature
- Hash the raw JSON request body:
body_hash = sha256(raw_request_body)
- Build the signing string:
sign_string = timestamp + "." + nonce + "." + hex(body_hash)
- Sign it with the app secret:
signature = base64(HMAC_SHA256(sign_string, app_secret))
Example
If:
timestamp = 1740892800nonce = d9b41d77c2a54d4c- raw body =
{"ticket":"abc123"}
Then the server expects a signature built in this shape:
1740892800.d9b41d77c2a54d4c.<hex_sha256_of_raw_body>
After HMAC-SHA256 signing with app_secret, send the Base64 result in X-Signature.
Integration notes
X-App-Idmust be the same agent UUID whose secret is used for signingX-Timestampmust be within about +/- 5 minutes of server timeX-Noncemust be unique for each request inside that time window- Reusing the same nonce causes the request to fail as replay protection
- Sign the exact JSON request body string that you actually send over HTTP, including spacing and field order
1. Issue Ticket
GET /api/v2/sso/ticket
Issues a one-time SSO ticket for the currently authenticated mobile user.
Required auth
This route is protected and requires a normal UC bearer token first:
Authorization: Bearer <access_token>
Query parameter
| Name | Required | Notes |
|---|---|---|
app_id | Yes | Agent UUID used as the target SSO app ID |
Example request
GET /api/v2/sso/ticket?app_id=9f7cc4a8-1111-2222-3333-8f2f07d22abc
Authorization: Bearer <access_token>
Success response
{
"status_code": 200,
"message": "Success",
"data": {
"ticket": "a3a64d8a3f2f2ec2f28e4b6d6f8bb52f7e9db53ed0f11fce7c9c380bcf8a0a92"
}
}
Important backend behavior
- The ticket is valid for about 5 minutes
- The provided
app_idmust resolve to a valid agent credential - If the bearer token already belongs to an agent, the
app_idmust belong to that same agent - The ticket is later consumed by
verify, not by app clients directly - After receiving the ticket, the app should hand it to your platform backend as soon as possible
2. Verify Ticket
POST /api/v2/sso/verify
Exchanges a one-time ticket for a normal UC access_token and refresh_token.
This call should normally be made by your platform backend, not by the mobile app directly.
Required headers
| Header | Required | Notes |
|---|---|---|
X-App-Id | Yes | Agent UUID |
X-Timestamp | Yes | Unix timestamp in seconds |
X-Nonce | Yes | Unique nonce for replay protection |
X-Signature | Yes | Base64 HMAC-SHA256 over timestamp.nonce.body_hash |
Request body
{
"ticket": "a3a64d8a3f2f2ec2f28e4b6d6f8bb52f7e9db53ed0f11fce7c9c380bcf8a0a92"
}
Success response
{
"status_code": 200,
"message": "Success",
"data": {
"user_id": "agent-user-10001",
"user_info": {
"name": "Wei Chen",
"phone": "855****1234"
},
"access_token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi...",
"expires_in": 1800
}
}
Response notes
user_idis the agent/platform-facing user IDuser_info.nameis resolved from display name, full name, or first/last name fallbackuser_info.phoneis masked before returningexpires_inis the access-token lifetime in seconds
Important backend behavior
- Signature validation happens before ticket validation
- The ticket is one-time use
- Expired or already-used tickets fail with
ticket expired or already used - The ticket must belong to the same
X-App-Id - The mobile user must still exist and be
ACTIVE user_idin the response may be your platform-shared user ID or an UC fallback ID when no shared ID has been configured
3. Refresh SSO Token Pair
POST /api/v2/sso/refresh
Refreshes an SSO-issued token pair using the same signed-header authentication model.
This call should normally be made by your platform backend, not by the mobile app directly.
Required headers
| Header | Required | Notes |
|---|---|---|
X-App-Id | Yes | Agent UUID |
X-Timestamp | Yes | Unix timestamp in seconds |
X-Nonce | Yes | Unique nonce for replay protection |
X-Signature | Yes | Base64 HMAC-SHA256 over timestamp.nonce.body_hash |
Request body
{
"access_token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi..."
}
Notes
refresh_tokenis requiredaccess_tokenis optional but supported
Success response
{
"status_code": 200,
"message": "Token refreshed successfully",
"data": {
"access_token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi...",
"expires_in": 1800
}
}
Important backend behavior
- Signature validation runs before refresh-token rotation
- The refresh flow reuses device ID
sso:<app_id> - The returned pair follows the same v2 auth refresh behavior as standard mobile-user auth
Common Failure Cases
- missing or invalid
app_id/X-App-Id - invalid app secret, causing signature verification failure
- timestamp outside the allowed 5-minute window
- duplicate nonce
- malformed JSON body
- expired or already-used ticket
- ticket issued for a different app
- inactive mobile user