Authentication

SSO

Issue, verify, and refresh SSO tickets in the v2 mobile API.

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:

  1. the mobile app calls UC with a normal bearer token to issue a one-time ticket
  2. your platform exchanges that ticket using signed server-to-server headers
  3. your platform refreshes the SSO-issued token pair with the same signed-header scheme

Who Calls What

StepCallerRoutePurpose
1Mobile appGET /api/v2/sso/ticketAsk UC for a one-time ticket for the already-authenticated user
2Your platform backendPOST /api/v2/sso/verifyExchange that ticket for an UC access_token and refresh_token
3Your platform backendPOST /api/v2/sso/refreshRefresh the SSO-issued token pair later

Important

  • The mobile app only needs to call the ticket endpoint
  • verify and refresh are intended for backend-to-backend integration
  • The signed-header rule below applies to verify and refresh, not to the ticket endpoint

Flow Summary

Step 1. Issue a one-time ticket
GET /api/v2/sso/ticket

Step 2. Exchange that ticket for tokens
POST /api/v2/sso/verify

Step 3. Refresh the SSO-issued token pair
POST /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

HeaderRequiredMeaning
X-App-IdYesAgent UUID
X-TimestampYesCurrent Unix timestamp in seconds
X-NonceYesUnique random value for replay protection
X-SignatureYesBase64 HMAC-SHA256 signature

How to build the signature

  1. Hash the raw JSON request body:
body_hash = sha256(raw_request_body)
  1. Build the signing string:
sign_string = timestamp + "." + nonce + "." + hex(body_hash)
  1. Sign it with the app secret:
signature = base64(HMAC_SHA256(sign_string, app_secret))

Example

If:

  • timestamp = 1740892800
  • nonce = 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-Id must be the same agent UUID whose secret is used for signing
  • X-Timestamp must be within about +/- 5 minutes of server time
  • X-Nonce must 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

NameRequiredNotes
app_idYesAgent 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_id must resolve to a valid agent credential
  • If the bearer token already belongs to an agent, the app_id must 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

HeaderRequiredNotes
X-App-IdYesAgent UUID
X-TimestampYesUnix timestamp in seconds
X-NonceYesUnique nonce for replay protection
X-SignatureYesBase64 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_id is the agent/platform-facing user ID
  • user_info.name is resolved from display name, full name, or first/last name fallback
  • user_info.phone is masked before returning
  • expires_in is 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_id in 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

HeaderRequiredNotes
X-App-IdYesAgent UUID
X-TimestampYesUnix timestamp in seconds
X-NonceYesUnique nonce for replay protection
X-SignatureYesBase64 HMAC-SHA256 over timestamp.nonce.body_hash

Request body

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi..."
}

Notes

  • refresh_token is required
  • access_token is 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
Copyright © 2026