SSO 单点登录
将你已有的业务系统账号体系无缝接入声邻 Voicelen。后端用 API Key 为指定账户换取一次性登录票据,前端用票据跳转到声邻 完成免密登录,用户感知不到登录流程。
接入流程
- ① 业务后端用 API Key 调用 POST /api/open/sso/ticket,传入 account 拿到 ticket 和 url
- ② 业务前端跳转到返回的 url(指向 https://app.voicelen.cn/sso?ticket=xxx)
- ③ 声邻 校验票据通过后,直接登入对应账户,用户进入主界面
使用须知
- account 是用户在你方业务系统中的稳定唯一标识(推荐邮箱 / 手机号 / 内部 user_id),后续同一个 account 始终对应同一个声邻 用户。
- ticket 有效期 60 秒、只能使用一次,使用后立即作废;请由业务后端按需生成,不要预生成或缓存。
- 如果 account 在声邻 还不存在,系统会按企业额度自动创建一个普通成员(member 角色)的账户;企业用户数已达上限时返回 4004。
- 生成票据接口仅校验 API Key 与账户合法性,不消耗通话余额;企业或用户被禁用时分别返回 3004 / 3005。
- 跳转目标固定为 https://app.voicelen.cn/sso,无需配置回调地址;前端拿到票据后透传即可。
生成登录票据
Section titled “生成登录票据”POST
/api/open/sso/ticket为指定账户生成一次性登录票据。业务后端调用,业务前端拿到 url 后跳转完成免密登录。
请求体
accountstring必填用户在你方业务系统中的稳定唯一标识(邮箱 / 手机号 / 用户名等),长度 1-100 字符;同一个 account 始终对应同一个声邻 用户,首次使用时按企业额度自动创建普通成员账户
响应字段
ticketstring一次性登录票据,仅可使用一次,使用后立即失效
urlstring直接可用的跳转地址,业务前端跳转到此 url 即可完成免密登录
expires_inint票据有效期(秒),固定 60
企业用户列表
Section titled “企业用户列表”GET
/api/open/users查询本企业的用户列表,可用于在业务系统中展示声邻 账户状态或挑选 account 后调用 SSO 票据接口。
查询参数
pageint可选页码,默认 1
page_sizeint可选每页数量,默认 10,最大 100
keywordstring可选关键词模糊匹配 username / email / phone / display_name
响应字段
uuidstring用户 UUID(声邻 内部标识)
usernamestring登录用户名,等同于创建该用户时使用的 account
emailstring邮箱,可为空
phonestring手机号,可为空
display_namestring展示名,可为空
rolestring角色:owner / admin / member
statusint状态:0 正常,1 禁用
created_atstring创建时间(RFC3339)