身份验证

FreeMaint 接受两种身份验证机制：JWT（由 /auth/login 颁发，由我们的 Web 和移动应用程序使用）和 API 密钥（在 /company-settings/api 中创建，由您自己的集成使用）。

JWT（用户会话）

1. POST /验证/登录 — 正文：{电子邮件、密码}。返回{access_token，refresh_token}。
2. 发送 Authorization 标头 — 每个请求都要带上：Authorization: Bearer <access_token>。
3. 过期后刷新 — 使用refresh_token POST /auth/refresh 以获取新的access_token。访问令牌持续 2 小时。

API 密钥（服务器集成）

1. 打开 /company-settings/api 或 /profile/api-keys — 管理员在「公司设置 > API」中创建密钥，适用于 Business 及以上套餐。角色拥有“创建个人 API 密钥”权限的人员，可在「个人资料 > 安全 > API 密钥」中创建自己的密钥。 拥有“管理集成”权限的角色（例如“集成管理员”模板）无需管理员身份即可创建、吊销和删除公司密钥；只有管理员才能把密钥转交给他人。
2. 单击“新密钥” — 可以选择设置到期时间和访问级别（默认为只读）。原始密钥只显示一次——请立即复制。
3. 使用它 — 在每个请求中发送 Authorization: Bearer fmk_<rawKey>。格式：以 fmk_ 开头，后跟 32 个十六进制字符。

安全说明

• API 密钥存储为 SHA-256 哈希值 — 一旦关闭显示对话框，原始值将无法恢复
• 撤销密钥会立即禁用它；该行被保留以供审计
• 每个密钥只属于一家公司，只能访问该公司的数据——其他公司的记录根本查不到
• 密钥可以有一个可选的 expiresAt 以进行短期集成
• 访问级别，是在所有者权限之上的一道上限：READ（默认，仅查询）、READ_STOCK（查询 + adjustStock，适合仅出库的自助终端）、FULL（所有者角色允许的所有操作）
• 每把密钥都以其所有者的身份行事：每次调用都带有所有者的权限和数据可见范围，密钥写入的内容也署所有者的名字。如果所有者被停用，密钥会被拒绝（401，代码 API_KEY_OWNER_INACTIVE），直到管理员在「公司设置 > API」中把它移交给另一个人——密钥值不会改变。

测试集成

没有独立的沙箱环境：API 密钥始终访问其所属公司的真实数据。有两种安全的测试方式。（1）使用第二家公司作为测试公司——公司之间的隔离与区分所有客户的机制完全相同，因此您在那里所做的任何操作都无法触及生产数据。API 密钥需要 Business 方案，因此该公司也必须使用 Business：免费公司无法创建密钥。（2）若只做读取，请创建访问级别为 READ 的密钥：它可以执行所有查询、不能执行任何变更，因此根本无法改动任何内容。当您准备写入时，READ_STOCK 密钥仅允许 adjustStock，别无其他。