PlainApp
API 参考

认证与令牌

设备登录与 token。登录后,token 与 c-id 必须属于同一会话。

设备登录流程

客户端
https://<host>:<port>/init
服务端

POST /init

HTTP request

c-id: clientId · body: empty

悬停或点按字段
1 / 7

sessionKey = Base64Decode(token)。登录时双方各自派生,不作为 Bearer 发送。logout 或 revokeSession 撤销登录会话;修改密码不会自动撤销。

在设备 App 的连接 → API 令牌中创建,成对复制 clientId 和 token。删除该令牌即可撤销。Bearer 只通过 HTTPS 发送。

HTTP 请求体加密不能保护下载的网页代码。首次使用需要可信的服务端身份;浏览器应使用可信 HTTPS。

未认证的连接过多时,服务器会在升级至 WebSocket 前返回 HTTP 429,响应体为空。请稍后再试。

WebSocket /auth · AuthErrorCode · 错误

首帧 10 秒;有效首帧后 60 秒内完成握手;登录及等待批准总计 300 秒。

INVALID_LOGIN_REQUEST
检查登录请求格式,再重新发起握手。
PASSWORD_SETUP_REQUIRED
先在设备上设置登录密码。
INVALID_PASSWORD
检查密码后重试。
PEER_IDENTITY_CHANGED
确认设备身份后再继续。
REMOTE_ACCESS_DISABLED
在设备上开启远程访问。
REJECTED
设备所有者拒绝了登录。
TIMEOUT
重新发起登录请求。
TOO_MANY_LOGIN_ATTEMPTS
稍后再试。

操作

http

Bearer API Token

使用独立 API Token,通过 HTTPS 发送 JSON,不做请求体加密。

bash
curl --request POST \
  --url 'https://<device-host>:<https-port>/graphql' \
  --header 'c-id: <client-id>' \
  --header 'Authorization: Bearer <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"{ app { deviceName capabilities access } }"}'
mutation

logout

撤销调用客户端当前的已认证会话。

graphql
mutation logout {
  logout
}