平台概述

统一身份认证中心 开放 API 提供标准化的统一身份认证能力，帮助第三方应用快速接入用户体系，实现单点登录、用户管理、安全审计等功能。

核心能力

快速接入

1. 创建应用

登录 管理后台，进入「应用管理」模块，点击「创建应用」获取 AppID 和 AppSecret。

2. 配置回调地址

在应用详情页配置授权回调地址（如 http://your-app.local/callback），用户授权后将跳转至此地址并携带 ticket 参数。

3. 接入 SDK

选择适合您技术栈的 SDK，参照对应语言的快速开始指南接入：

4. 测试连通性

使用 AppID 和 AppSecret 调用测试接口，验证网络连通与凭证正确性。

认证流程

SSO 单点登录流程

Step 1: 构建授权 URL

Step 2: 换取 Token

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "ok": true,
    "token": "3f2a9c...e17b",
    "expires_in": 604800,
    "uid": 18,
    "username": "zhangsan"
  }
}

API 参考 - 认证接口

SSO 相关

sso.authorize - 发起授权（浏览器跳转）

由浏览器发起。已登录则 302 重定向到回调地址并附带 ticket；未登录返回 401 并在 data 中给出 login_url。

sso.test - 通信测试

验证应用凭证与网络连通性。

// 成功响应
{
  "code": 0,
  "message": "ok",
  "data": {
    "ok": true,
    "message": "通信正常",
    "data": {
      "app_name": "我的应用",
      "status": 1,
      "sso_enabled": 1,
      "callbacks": ["https://app.example.com/callback"],
      "ticket_test": "ok",
      "server_time": 1789878021
    }
  }
}

sso.exchange - 换取 Token

用授权回调获取的 ticket 换取访问令牌。ticket 一次性且有效期很短，换取后立即失效。

// 成功响应（注意：当前版本不返回 refresh_token）
{
  "code": 0,
  "message": "ok",
  "data": {
    "ok": true,
    "token": "3f2a9c...e17b",
    "expires_in": 604800,
    "uid": 18,
    "username": "zhangsan"
  }
}

sso.userinfo - 获取用户信息

{
  "code": 0,
  "message": "ok",
  "data": {
    "ok": true,
    "user": {
      "uid": 18,
      "username": "zhangsan",
      "nickname": "张三",
      "avatar": "https://.../avatar.png",
      "email": "z@example.com",
      "mobile": "13800000000",
      "gender": 0,
      "birthday": "",
      "bio": "",
      "status": "normal"
    }
  }
}

sso.logout - 单点退出

吊销该 token 对应的登录态（仅影响当前令牌）。

API 参考 - 用户接口

以下接口需要用户已登录（携带会话 Cookie）或通过 Token 认证。

user.register - 用户注册

{
  "code": 0, "message": "注册成功",
  "data": { "ok": true, "uid": 18, "sid": "a1b2c3...", "placeholder_email": false }
}

user.login - 用户登录

{
  "code": 0, "message": "ok",
  "data": { "ok": true, "uid": 18, "username": "zhangsan", "sid": "a1b2c3..." }
}

user.info - 获取用户信息

无请求参数，需已登录。

{
  "code": 0, "message": "ok",
  "data": {
    "uid": 18, "username": "zhangsan", "nickname": "张三",
    "email": "z@example.com", "email_bound": true,
    "mobile": "13800000000", "avatar": "https://.../a.png",
    "gender": 0, "gender_text": "未知", "birthday": "", "bio": "",
    "register_text": "2026-09-20 10:00", "last_login_text": "刚刚",
    "last_login_ip": "127.0.0.1", "status": "normal", "status_text": "正常",
    "source": "UCenter"
  }
}

user.security - 账号安全（设备与登录历史）

无请求参数。返回 devices（当前在线设备）与 history（最近 50 条登录/退出记录）。

user.logout / user.logoutall - 退出登录

logoutall 返回 { ok: true, revoked: n }，n 为被撤销的会话数。

user.device_kill - 踢掉指定设备

user.check - 账号唯一性检查

{ "code": 0, "message": "ok", "data": { "ok": true, "available": true, "code": 1, "message": "可以注册" } }

user.password - 修改密码

成功后返回 { ok: true, relogin: true }，修改后其他设备会被注销。

user.profile - 修改资料

user.findpwd_send - 发送找回密码验证码

仅在 debug 开启时响应会附带 debug_code 便于本地联调；生产环境请务必关闭 debug。

user.findpwd_reset - 用验证码重置密码

user.oauth_unbind - 解除第三方绑定

user.deletion_request - 提交账号注销申请

提交后进入后台审核，审核通过后账号停用并移入回收站。

API 参考 - 验证码接口

无需登录即可调用。

captcha.issue - 获取验证码

// slide 样式
{
  "code": 0, "message": "ok",
  "data": {
    "token": "8f3c...a91d", "style": "slide",
    "bg": "data:image/png;base64,...",     // 背景图（带缺口）
    "piece": "data:image/png;base64,...",  // 待拖动的拼图块
    "mime": "image/png",
    "size": 50, "width": 300, "height": 150,
    "hole_x": 137, "hole_y": 62            // 缺口左边缘坐标，用于定位拼图块
  }
}

// digits / mixed 样式
{
  "code": 0, "message": "ok",
  "data": { "token": "8f3c...a91d", "style": "digits", "image": "data:image/png;base64,...", "mime": "image/png" }
}

captcha.verify - 校验验证码

API 参考 - 管理接口

admin.user_list - 用户列表

权限点：view:users

{
  "code": 0, "message": "ok",
  "data": {
    "total": 128,
    "rows": [{ "uid": 18, "username": "zhangsan", "email": "z@example.com", "nickname": "张三",
               "mobile": "13800000000", "gender_text": "未知", "sync_status": 1, "uc_ok": 1 }],
    "page": 1, "size": 20
  }
}

admin.session_list - 会话列表

权限点：view:sessions

admin.log_list - 系统日志

权限点：view:logs

管理接口速查表（RBAC 权限点）

SDK 下载中心

完整 SDK 压缩包由系统后台统一维护，上传后自动同步到本页面，点击即可下载。

PHP SDK

安装

# 本地集成：将 sdk 目录放入项目，并在 composer.json 中配置：
"repositories": [
    { "type": "path", "url": "./sdk" }
],
"require": { "uic/sdk": "*" }
# 然后执行：composer require uic/sdk

快速开始

复制<?php
require_once 'vendor/autoload.php';

use UIC\SDK\Client;

$client = new Client([
    'base_url'   => 'http://127.0.0.5',
    'app_id'     => 'your_app_id',
    'app_secret' => 'your_app_secret',
]);

// 获取授权 URL
$authUrl = $client->auth()->getAuthorizeUrl(
    'http://your-app.local/callback',
    bin2hex(random_bytes(16))
);

// 换取 Token（在回调页面执行）
$tokenData = $client->auth()->exchangeToken($_GET['ticket']);

// 获取用户信息
$user = $client->auth()->getUserInfo();
echo "欢迎，" . $user['nickname'];
?>

完整功能示例

// 通信测试
$ok = $client->auth()->testConnect();

// 获取授权 URL
$url = $client->auth()->getAuthorizeUrl($callback, $state);

// 换取 Token
$tokens = $client->auth()->exchangeToken($ticket);

// 获取用户信息
$user = $client->auth()->getUserInfo();

// 单点退出
$client->auth()->logout();

// 用户注册
$user = $client->user()->register([
    'username' => 'newuser',
    'password' => 'Password123',
    'confirm'  => 'Password123',
    'email'    => 'user@example.com',
], true);

// 用户登录
$client->user()->login('username', 'password', true);

// 获取信息
$info = $client->user()->getInfo();

// 修改密码
$client->user()->changePassword('old123', 'new123', 'new123');

// 修改资料
$client->user()->updateProfile(['nickname' => '新昵称']);

// 检查用户名是否可用
$available = $client->user()->checkUnique('username', 'testname');

// 获取验证码
$captcha = $client->captcha()->issue('digits');
echo "Token: " . $captcha['token'];

// 校验验证码
$ok = $client->captcha()->verify($captcha['token'], '1234');

JavaScript SDK

安装

# 本地使用：将 sdk/js 目录放入项目，或通过 npm link 引入
npm install ./sdk/js
# 或
yarn add ./sdk/js

浏览器环境

引入方式：SDK 文件不在站点公开目录下，不能直接用 /sdk/js/dist/uic-sdk.js 引用。 请从下方「SDK 下载」获取 js/dist/uic-sdk.js 后自行托管，再按实际路径引入：

<!-- 自托管后按实际路径引入 -->
<script src="/your-static/uic-sdk.js"></script>
<script>
const client = new UIC.Client({
    baseUrl: 'https://open.heicat.com',
    appId: 'your_app_id',
    appSecret: 'your_app_secret' // 仅限服务端使用
});

// 跳转到授权页（同步返回 URL 字符串）
const url = client.auth.getAuthorizeUrl('http://your-app.local/callback');
window.location.href = url;
</script>

Node.js 环境

const { Client } = require('uic-sdk');

const client = new Client({
    baseUrl: 'https://open.heicat.com',
    appId: 'your_app_id',
    appSecret: 'your_app_secret'
});

async function main() {
    // 换取 Token
    const tokens = await client.auth.exchangeToken(req.query.ticket);

    // 获取用户信息
    const user = await client.auth.getUserInfo(tokens.token);
    console.log(user);
}

main();

Python SDK

安装

pip install uic-sdk

同步调用

from uic_sdk import Client

client = Client(
    base_url='http://127.0.0.5',
    app_id='your_app_id',
    app_secret='your_app_secret'
)

# 获取授权 URL
auth_url = client.auth.get_authorize_url(
    callback='http://your-app.local/callback',
    state='random_state_string'
)

# 换取 Token
tokens = client.auth.exchange_ticket(ticket='ticket_from_callback')

# 获取用户信息
user = client.auth.get_user_info(token=tokens['token'])
print(f"欢迎，{user['nickname']}")

异步调用（asyncio）

import asyncio
from uic_sdk import AsyncClient

async def main():
    client = AsyncClient(
        base_url='https://open.heicat.com',
        app_id='your_app_id',
        app_secret='your_app_secret'
    )
    try:
        # 换取 Token
        tokens = await client.auth.exchange_ticket('ticket_from_callback')

        # 获取用户信息
        user = await client.auth.get_user_info(token=tokens['token'])
        print(user)
    finally:
        await client.close()  # 关闭底层连接池

asyncio.run(main())

Flask 集成示例

from flask import Flask, request, redirect
from uic_sdk import Client

app = Flask(__name__)
client = Client(base_url='...', app_id='...', app_secret='...')

@app.route('/login')
def login():
    url = client.auth.get_authorize_url('http://your-app.local/callback')
    return redirect(url)

@app.route('/callback')
def callback():
    ticket = request.args.get('ticket')
    tokens = client.auth.exchange_ticket(ticket)
    session['token'] = tokens['token']
    return '登录成功'

Go SDK

安装

# 方式一：本地集成（推荐，SDK 无外部依赖，仅用标准库）
# 将 sdk/go 目录复制到项目，在 go.mod 中引用：
replace github.com/uic/sdk-go => ./sdk/go

# 方式二：复制源码后直接作为本地包使用（demo 目录即此方式）
go run ./demo

快速开始

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    uicsdk "github.com/uic/sdk-go"
)

func main() {
    // 初始化客户端（选项式配置：超时 / 日志 / 重试 / context）
    client := uicsdk.NewClient(
        "https://open.heicat.com",
        uicsdk.WithTimeout(10*time.Second),
        uicsdk.WithRetry(3, 100*time.Millisecond, 2*time.Second),
        uicsdk.WithContext(context.Background()),
    )
    client.SetAppCredentials("your_app_id", "your_app_secret")

    // 获取授权 URL
    authURL := client.AuthorizeURL("your_app_id", "http://your-app.local/callback")
    fmt.Println("授权URL:", authURL)

    // 换取 Token（在服务端回调中执行）
    tokens, err := client.Exchange("ticket_from_callback", "", "")
    if err != nil {
        log.Fatal(err)
    }

    // 获取用户信息
    user, err := client.Userinfo(tokens["token"].(string), "")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("欢迎，%s\n", user["nickname"])
}

Gin 框架集成

package main

import (
    "net/http"
    "time"

    "github.com/gin-gonic/gin"
    uicsdk "github.com/uic/sdk-go"
)

func main() {
    r := gin.Default()
    client := uicsdk.NewClient(
        "https://open.heicat.com",
        uicsdk.WithTimeout(10*time.Second),
        uicsdk.WithRetry(3, 100*time.Millisecond, 2*time.Second),
    )
    client.SetAppCredentials("your_app_id", "your_app_secret")

    r.GET("/login", func(c *gin.Context) {
        url := client.AuthorizeURL("your_app_id", "http://your-app.local/callback")
        c.Redirect(http.StatusFound, url)
    })

    r.GET("/callback", func(c *gin.Context) {
        ticket := c.Query("ticket")
        tokens, err := client.Exchange(ticket, "", "")
        if err != nil {
            c.JSON(400, gin.H{"error": err.Error()})
            return
        }
        c.JSON(200, tokens)
    })

    r.Run(":8080")
}

错误码表

UCenter / 业务子码（出现在 data.code 或 message 中）

通用响应格式

// 成功（message 成功时默认为 "ok"）
{
  "code": 0,
  "message": "ok",
  "data": { ... },
  "time": 1789878021
}

// 错误（HTTP 状态码仍为 200）
{
  "code": 401,
  "message": "请先登录",
  "data": null,
  "time": 1789878021
}

高级功能：重试 · 批量 · 连接池

SDK v1.1.0 起内置生产可用级的容错能力。各语言实现程度如下：

① PHP SDK：配置指数退避重试

// 创建客户端时传入重试配置（默认关闭）
$client = new UIC\SDK\Client([
    'base_url'   => 'https://open.heicat.com',
    'app_id'     => 'your_app_id',
    'app_secret' => 'your_app_secret',
    // 重试策略：false 关闭（默认）；数组开启
    'retry' => [
        'max_retries'   => 3,   // 最大重试次数
        'base_delay_ms' => 100, // 初始退避 100ms（指数增长）
        'max_delay_ms'  => 5000,// 最大退避 5s
    ],
]);

// 仅对可重试错误重试：网络错误、HTTP 429/500/502/503/504
// 业务错误码（如 401 参数错误）不会重试，避免无效放大请求量

② PHP SDK：批量操作（单条失败不中断）

// 批量查询多个 Token 对应的用户信息
$result = $client->user()->batchInfo(
    ['token_a', 'token_b', 'token_c'],
    5 // 并发数，默认 5
);
foreach ($result['items'] as $item) {
    if (!empty($item['_error'])) {
        echo "失败: " . $item['_error'] . "\n";
    } else {
        echo $item['user']['nickname'] . "\n";
    }
}

// 批量注册用户
$result = $client->user()->batchRegister([
    ['username' => 'u1', 'password' => 'Passw0rd!', 'confirm' => 'Passw0rd!'],
    ['username' => 'u2', 'password' => 'Passw0rd!', 'confirm' => 'Passw0rd!'],
]);
echo "成功 {$result['ok']} 条，失败 {$result['fail']} 条";

③ Go SDK：重试 + context 取消 + 连接池

client := uicsdk.NewClient(
    "https://open.heicat.com",
    uicsdk.WithTimeout(10*time.Second),
    uicsdk.WithRetry(3, 100*time.Millisecond, 2*time.Second), // 指数退避 + 抖动
    uicsdk.WithContext(ctx),  // 全局取消上下文，传入即生效
)
// 连接池：默认 MaxIdleConns=100、MaxIdleConnsPerHost=10，自动复用 keep-alive 连接

④ 调用建议

• 重试只用于幂等操作：查询、开通类接口可安全重试；注册、转账等写操作失败后请核对是否已生效，避免重复提交。
• 限流：服务端当前仅在「登录失败锁定」「短信发送频率」「IP 访问策略」三处做限制，尚未提供全局 QPS 限流，不会返回 429；公网部署建议在网关层（Nginx / WAF）自行补充。
• 批量操作建议：单批建议 50 条以内；大量导入请拆批并做好失败记录（_error 字段）。
• 连接池注意：Python 同步客户端使用 requests.Session 复用连接，程序退出前无需特殊处理；异步客户端使用完请 await client.close()。

常见问题

Q1: 如何获取 AppID 和 AppSecret？

登录管理后台，进入「应用管理」模块，点击「创建应用」即可获得。每个应用对应一套独立的凭证。

Q2: 回调地址可以配置多个吗？

可以。应用支持配置多个回调地址（后台「应用管理」中以英文逗号或换行分隔）， 授权时传入的 redirect 必须在白名单内，否则会被拒绝。开发/测试/生产多环境直接配多条即可，无需创建多个应用。 应用还支持 ip_whitelist 限制回调来源。

Q3: Token 有效期多长？如何刷新？

Access Token 有效期由后台 sso.token_ttl 配置，默认 604800 秒（7 天）。 当前版本不支持 Refresh Token，过期后需重新引导用户授权换取新的 Token。

Q4: 支持哪些部署环境？

PHP SDK 支持 PHP 7.4+，其他语言 SDK 支持对应语言的主流版本。服务端需开启 ext-json 和 ext-curl 扩展。

Q5: 本地开发如何测试？

建议在本地 hosts 中配置域名（如 uic.local），或使用 127.0.0.5 作为开发地址。确保回调地址与配置一致。

Q6: 生产环境安全注意事项？

1) 务必启用 HTTPS；2) AppSecret 存储在服务端环境变量；3) 定期轮换 AppSecret；4) 开启 IP 白名单限制。

更新日志

v1.1.0 (2026-09-20)

• PHP SDK：新增指数退避重试机制（config.retry 可配置，默认关闭）
• PHP SDK：新增批量操作 batchInfo() / batchRegister()，单条失败不中断
• Go SDK：新增 WithRetry（重试+抖动）、WithContext（取消控制）、WithTimeout
• Go SDK：默认启用 HTTP 连接池（MaxIdleConns=100 / MaxIdleConnsPerHost=10）
• Go SDK：补齐用户接口与验证码接口（register/login/info/password/check/captcha）
• Python SDK：AsyncClient 子客户端（auth/user/captcha）实现真正的异步调用，支持连接池复用
• JavaScript SDK：浏览器 UMD 包 + Node.js CJS 双环境支持
• 新增 PHPUnit 单元测试（30 tests / 69 assertions）、JS 冒烟测试、Python pytest 测试
• 开放文档页面上线：多语言 SDK 切换、错误码表、快速接入指南、高级功能说明

v1.0.0 (2026-09-20)

• 初始版本发布
• 支持 SSO 单点登录（OAuth2.0 简化模式）
• 支持用户注册、登录、改密、资料管理
• 支持图形验证码（滑块/数字/混合）
• 提供 PHP、JavaScript、Python、Go 四种语言 SDK

v1.2.0 (2026-09-21)

• 文档与实现对齐：修正管理接口参数名（user_list 改为 kw/page/size，log_list 改为 type/level/uid/app_id/kw/page/size，session_list size 钳制 10~50）
• 修正 sso.exchange 响应示例：移除未实现的 refresh_token 字段
• 补齐用户接口文档：security / logout / logoutall / device_kill / check / oauth_unbind / deletion_request
• 补齐 SSO 文档：authorize 跳转语义、test / userinfo / logout 参数与响应示例
• 新增管理接口 RBAC 权限点速查表（30+ 接口）
• 错误码表重构：明确「HTTP 恒为 200、业务码在 code 字段」，移除未实现的 429 / 503，补充业务子码 -1~-8
• 补充滑块验证码对接说明（hole_x/hole_y 定位、容差 10px）与「校验即作废」注意事项
• 修正 FAQ：回调地址支持多个（原描述为仅单个，与实现不符）

路线图

• v1.2.0 - Refresh Token 自动刷新机制
• v1.3.0 - WebHook 事件通知
• v1.4.0 - JS/Python SDK 增加重试与批量能力
• v2.0.0 - OAuth2.0 授权码模式