选择接入方式

光年的单码登录分为标准单码登录与 Connect 单码登录。标准单码登录可使用 HTTP API 或官方 SDK。

开始前准备

步骤 1 · 平台创建项目

填写项目名称，新 HTTP 客户端选择 V3，并记录列表中的程序 ID。

打开创建项目

步骤 2 · 平台检查接口策略

在接口中心选择程序；基础接口会默认启用，权益等级接口按当前等级开放，用户自助接口再按需开通。

打开接口中心

步骤 3 · 平台生成测试卡密

创建一张专用测试卡，避免用正式用户卡反复联调。

生成测试卡密

步骤 4 · 客户端实现登录与结果判断

按选定协议发送字段，先处理业务结果，再按需接入 SDK 心跳。

查看登录接口 →

C / C++ 客户端使用 SDK 时，还要在项目配置中开启 SDK 接入。项目配置属于单个项目，请先进入项目列表，再点击该项目的“配置”。

完成开发后使用上线检查清单逐项验证，不要只确认一次登录成功。

接入方式对照

接入方式	地址	认证方式	会话
标准 HTTP V3	POST /api/legacy/v3/cards/login	HMAC-SHA256 请求头	客户端按接口响应处理
标准 HTTP V1	POST /api/card_login	MD5 参数签名	仅旧项目使用
官方 SDK	POST /api/v1/cards/login	SDK 自动签名	SDK 管理令牌与心跳
Connect	POST /connect/{程序ID}	无签名	返回独立 token

推荐选择

新项目优先选择标准 HTTP V3。C / C++ 软件需要完整会话守护时使用官方 SDK。只有明确需要简化兼容接口时才使用 Connect。

授权与计量

标准 HTTP 与官方 SDK 共用一份 card_login 授权和配额；Connect 是否默认启用由管理员的接口开放策略决定，也可以在当前程序的 Connect 配置页单独关闭或启用。

最小字段

标准 HTTP

• app：程序 ID
• kami：卡密
• imei：设备码
• V3 还必须携带 X-GN-Timestamp、X-GN-Nonce、X-GN-Signature

Connect

• 程序 ID 位于 URL
• user_key：卡密
• serial：设备码
• nonce：可选
• game：仅兼容旧客户端的可选标识，新客户端不要传

不要把 app/kami/imei 与 user_key/serial 混在同一个请求中。

判断结果

• 标准 HTTP 卡密登录：业务 code === 0 才是登录成功（响应同时带 success）。
• 标准 HTTP 解绑：成功码是 code === 1，与登录不同，不要复用登录判断。
• SDK：以 SDK 返回值和会话状态为准。
• Connect：status === true 才是成功。
• HTTP 200 只表示服务器返回了内容，不代表授权通过。Connect 的业务失败（卡密无效等）刻意返回 HTTP 200 + status:false， 兼容旧客户端只解析 JSON 主体的习惯；只有签名/安全类异常才使用真实 HTTP 状态码。因此任何协议都不能只看 HTTP 状态码。

下一步：查看标准单码登录接口 或 接入登录会话与心跳。