cert-ctrl HTTP API 参考

本文列出当前服务端已注册的 HTTP 端点，面向客户端集成与自动化场景。

约定

Base URL（本地）: http://localhost:8080 或 https://localhost:10000（TLS 代理）
会话 Cookie: cjj365=<session_id>
API Key 认证: Authorization: Bearer ak_...
设备认证: Authorization: Bearer <jwt> 用于 /apiv1/devices/self/*
响应包裹:
- 成功: 200/201/204，可选 { "data": ... }
- 失败: >= 400，{ "error": { "code": int, "what": string } }
分页: 多数列表接口支持 offset 和 limit（默认 100）
用户作用域: /apiv1/users/:user_id/... 或 /apiv1/me/...

认证与会话

路径

GET /auth/general - 辅助检查（例如用户名可用性）
POST /auth/general - 登录/注册/重置（通过 action）
GET /auth/status - 会话状态
POST /auth/logout - 登出并清理会话
GET /auth/profile - 当前用户概览
GET /auth/third-party-bindings - 已绑定的第三方
POST /auth/refresh - 刷新会话
POST /auth/device - 设备登录流程
GET /auth/weixin、GET /auth/weixin/callback
GET /auth/github、GET /auth/github/callback
GET /auth/solana
POST /auth/webauthn/register/options
POST /auth/webauthn/register/verify
POST /auth/webauthn/login/options
POST /auth/webauthn/login/verify
POST /auth/webauthn/step-up/options
POST /auth/webauthn/step-up/verify
GET /auth/webauthn/credentials
DELETE /auth/webauthn/credentials/:id

登录示例

curl -X POST https://cjj365.cc/auth/general \
  -H "Content-Type: application/json" \
  -d '{"action":"login","email":"user@example.com","password":"password"}' \
  -c cookies.txt

健康检查

GET /health

目录与元数据

GET /apiv1/permissions/catalog - API Key 权限范围
GET /apiv1/dns/providers/catalog - DNS 服务商目录
GET /apiv1/payment/channels - 支付渠道
GET /apiv1/fx-rates - 汇率（公开）

设备注册

路径

POST /apiv1/device/registration

说明

需要 user_id、device_public_id、registration_code、dev_pk（base64，解码后 32 字节）。
响应包含设备记录与设备会话 token。

设备（需要会话）

基础路径

/apiv1/users/:user_id/devices
/apiv1/users/:user_id/devices/:device_id
/apiv1/users/:user_id/devices/by-public-id/:device_public_id
/apiv1/users/:user_id/devices/:device_id/certificates
/apiv1/users/:user_id/devices/:device_id/certificates/:certificate_id
/apiv1/users/:user_id/devices/:device_id/certificates/:certificate_id/bundle
/apiv1/users/:user_id/devices/:device_id/cas
/apiv1/users/:user_id/devices/:device_id/cas/:ca_id
/apiv1/users/:user_id/devices/:device_id/cas/:ca_id/bundle
/apiv1/users/:user_id/devices/:device_id/install-config
/apiv1/users/:user_id/devices/:device_id/install-config/restore
/apiv1/users/:user_id/devices/:device_id/install-config-histories
/apiv1/users/:user_id/devices/:device_id/config-files
/apiv1/users/:user_id/devices/:device_id/config-files/:file
/apiv1/me/devices 及其别名路径

说明

GET /apiv1/users/:user_id/devices/:device_id 当前未实现（返回 501）。
API Key 分配证书请使用 POST /apiv1/me/certificate-assign。

设备自助端点（设备 JWT）

GET /apiv1/devices/self/updates
- 需要 Authorization: Bearer <jwt>，token 内含 device_id。
- Query: cursor（Redis stream id）、limit（1-100）。If-None-Match 可携带 cursor。
- 无更新时返回 204，带 ETag 与 X-Poll-Interval。
GET /apiv1/devices/self/certificates/:certificate_id/deploy-materials
GET /apiv1/devices/self/certificates/:certificate_id（别名）
GET /apiv1/devices/self/cas/:ca_id/bundle
GET /apiv1/devices/self/install-config
POST /apiv1/devices/self/notify

证书（需要会话）

路径

/apiv1/users/:user_id/certificates
/apiv1/users/:user_id/acme-accounts/:acme_account_id/certificates
/apiv1/users/:user_id/certificates/:certificate_id
/apiv1/users/:user_id/certificates/:certificate_id/issues
/apiv1/users/:user_id/certificates/:certificate_id/issues/history
/apiv1/users/:user_id/certificates/:certificate_id/issue-result
/apiv1/users/:user_id/certificates/:certificate_id/export
/apiv1/me/certificates 及其别名路径

说明

POST /.../issues 发起签发或续期。
GET /.../issues 返回签发历史。
PUT /.../issue-result 由 worker 上传签发结果。
GET /.../export 支持 format=zip。

创建证书示例

curl -X POST https://cjj365.cc/apiv1/users/1/certificates \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "domain_name": "example.com",
    "sans": ["example.com", "www.example.com"],
    "acct_id": 7,
    "action": "create",
    "key_algorithm": "ECDSA",
    "policy": "HYBRID"
  }'

内部 worker 端点

POST /apiv1/internal/certificates/:certificate_id/challenges/http01/start
POST /apiv1/internal/certificates/:certificate_id/challenges/http01/stop
POST /apiv1/internal/certificates/:certificate_id/challenges/tlsalpn01/start
POST /apiv1/internal/certificates/:certificate_id/challenges/tlsalpn01/stop

ACME 账户（需要会话）

GET /apiv1/users/:user_id/acme-accounts
POST /apiv1/users/:user_id/acme-accounts
GET /apiv1/users/:user_id/acme-accounts/:acme_account_id
PUT /apiv1/users/:user_id/acme-accounts/:acme_account_id
DELETE /apiv1/users/:user_id/acme-accounts/:acme_account_id
/apiv1/me/acme-accounts 别名

提示：API Key 权限作用域名称为 acme_accounts（下划线）。

证书机构（需要会话）

GET /apiv1/users/:user_id/cas
POST /apiv1/users/:user_id/cas
GET /apiv1/users/:user_id/cas/:ca_id
PUT /apiv1/users/:user_id/cas/:ca_id
DELETE /apiv1/users/:user_id/cas/:ca_id
POST /apiv1/users/:user_id/cas/:ca_id/issue

API Key（需要会话）

GET /apiv1/users/:user_id/apikeys
POST /apiv1/users/:user_id/apikeys
GET /apiv1/users/:user_id/apikeys/:apikey_id
PATCH /apiv1/users/:user_id/apikeys/:apikey_id（更新权限）
DELETE /apiv1/users/:user_id/apikeys/:apikey_id
/apiv1/me/apikeys 别名

安装配置更新（API Key）

POST /apiv1/me/install-config-update/:device_public_id

需要 API Key 权限 ForInstallConfigUpdate 且包含 update 动作。请求体可以是补丁数组或包含 patches 与可选 after_update_script 的对象。

{
  "patches": [
    {"ob_type":"cert","ob_id":10,"enabled":true,"to":"/etc/ssl/cert.pem"}
  ],
  "after_update_script":"systemctl reload nginx"
}

自动化分配（API Key）

POST /apiv1/me/certificate-assign

证书 id 从 API Key 权限推导（certificates + read 且 obid 为具体 id）。请求体仅需 device_public_id。

Git 托管与代理

GET /apiv1/users/:user_id/proxy_credentials
GET /apiv1/users/:user_id/gitrepos
GET /apiv1/users/:user_id/gitrepos/:repo_id/tags
/apiv1/users/:user_id/gitrepos/:repo_id/*
/git/*（Git HTTP）

通知与隧道

/apiv1/users/:user_id/notifications/channels
/apiv1/users/:user_id/notifications/channels/:channel_id
/apiv1/users/:user_id/notifications/channels/:channel_id/verify-email
/apiv1/users/:user_id/notifications/channels/:channel_id/resend-email
/apiv1/users/:user_id/notifications/subscriptions
/apiv1/users/:user_id/notifications/subscriptions/:event_key/:channel
/apiv1/users/:user_id/notifications/subscriptions/:event_key/:channel/
/apiv1/users/:user_id/notifications/wechat/handshake
/apiv1/users/:user_id/notifications/wechat/handshake/:handshake_token
/apiv1/notifications/templates
/apiv1/notifications/templates/:template_id
/apiv1/users/:user_id/tunnel_sessions
/apiv1/users/:user_id/tunnel_webhook_logs

钱包与支付

/apiv1/users/:user_id/wallets
/apiv1/users/:user_id/wallets/:wallet_id
/apiv1/users/:user_id/wallets/:wallet_id/issue-charges
/apiv1/users/:user_id/wallets/:wallet_id/outstanding-charges
/apiv1/users/:user_id/wallet-conversions
/apiv1/users/:user_id/wallet-conversions/:conversion_id
/apiv1/users/:user_id/payment-quotes
/apiv1/users/:user_id/payment-quotes/:payment_quote_id
/apiv1/users/:user_id/price-plans/current
/apiv1/users/:user_id/payments
/apiv1/users/:user_id/payments/:payment_id
/apiv1/users/:user_id/wallets/:wallet_id/topups
/apiv1/users/:user_id/wallets/:wallet_id/topups/:topup_id
/apiv1/users/:user_id/wallet-topups
/apiv1/users/:user_id/topup-history
POST /apiv1/users/:user_id/alipay/page-pay
POST /apiv1/alipay/notify
POST /apiv1/users/:user_id/wechat/native-pay
GET /apiv1/users/:user_id/wechat/native-pay/:out_trade_no/status
POST /apiv1/wechatpay/notify

管理员接口

/apiv1/admin/pricing/plans
/apiv1/admin/pricing/plans/:plan_id
/apiv1/admin/pricing/plans/reload
/apiv1/admin/pricing/markets/reload
/apiv1/admin/wallet-topups
/apiv1/admin/wallet-topups/:topup_id/settle
/apiv1/admin/wallet-topups/:topup_id/reject
/apiv1/admin/wallet-topups/:topup_id/reactivate
/apiv1/admin/users
/apiv1/admin/users/:user_id/wallets
/apiv1/admin/users/:user_id/resend-activation-email
/apiv1/admin/stablecoin-keyrings
/apiv1/admin/stablecoin-keyrings/:keyring_id/release
/apiv1/admin/stablecoin-keyrings/:keyring_id/retire
/apiv1/admin/stablecoin-keyrings/import
/apiv1/admin/stablecoin-seeds
/apiv1/admin/fx-rates

其他

/apiv1/iroiro（实验性）

约定​

认证与会话​

健康检查​

目录与元数据​

设备注册​

设备（需要会话）​

设备自助端点（设备 JWT）​

证书（需要会话）​

ACME 账户（需要会话）​

证书机构（需要会话）​

API Key（需要会话）​

安装配置更新（API Key）​

自动化分配（API Key）​

Git 托管与代理​

通知与隧道​

钱包与支付​

管理员接口​

其他​

相关文档​

约定