身份验证 - FIM One

概述

FIM One API 支持两种身份验证方法：

API 密钥 — 用于服务间集成的简单、长期有效的令牌
JWT 令牌 — 来自用户登录的短期令牌（用于 SSE 端点）

大多数集成应使用 API 密钥。

API 密钥

API 密钥是与您的用户账户关联的长期凭证。它们适用于：

服务器到服务器的集成
计划脚本和自动化
外部应用程序访问 FIM One

创建 API 密钥

登录到您的 FIM One 门户
转到 设置 → API 密钥
点击 创建 API 密钥
输入名称（例如，“生产集成”）
（可选）设置作用域以限制访问权限
（可选）设置过期日期
点击创建
立即复制密钥 — 它只会显示一次

完整密钥看起来像：fim_your44characterkeystringhere（以 fim_ 前缀开头）

使用 API 密钥

在 Authorization 标头中将密钥作为 Bearer 令牌包含：

curl -H "Authorization: Bearer fim_your_api_key_here" \
  https://your-domain.com/api/conversations

或在 Python 中：

import requests

headers = {
    "Authorization": "Bearer fim_your_api_key_here"
}

response = requests.get(
    "https://your-domain.com/api/conversations",
    headers=headers
)
print(response.json())

API 密钥功能

可见性: 每个密钥显示：

密钥前缀（前 8 个字符用于识别）
创建日期
最后使用时间戳
总请求数
活跃状态
过期日期（如果设置）

管理: 您可以：

启用/禁用密钥而无需删除它们
设置自动过期日期
永久删除密钥
跟踪使用模式

作用域

作用域限制 API 密钥可以访问的内容。如果未设置作用域，密钥具有完全访问权限。可用作用域：

作用域	允许
`chat`	POST /api/react, POST /api/dag, POST /api/chat/inject
`agents`	GET /api/agents, GET /api/agents/`{id}`
`kb`	GET /api/knowledge-bases, POST /api/knowledge-bases/`{id}`/retrieve
`connectors`	连接器 CRUD（connector_specific 端点）
`admin`	管理端点

创建具有作用域的密钥：

curl -X POST https://your-domain.com/api/me/api-keys \
  -H "Authorization: Bearer your_current_api_key_or_jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chat-only Integration",
    "scopes": "chat"
  }'

JWT 令牌

JWT 令牌是短期的，在登录时颁发。它们用于：

SSE 流式端点：在 /api/react 和 /api/dag 的请求体中传递令牌
门户会话：前端身份验证

获取 JWT Token

当您通过网络门户登录或调用身份验证端点时，JWT token 会自动颁发：

curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

响应：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 7200,
  "user": { ... }
}

使用 JWT 进行流式传输

对于 SSE 端点，在请求体中包含令牌：

curl -X POST https://your-domain.com/api/react \
  -H "Content-Type: application/json" \
  -d '{
    "q": "What are the top 3 Python frameworks?",
    "token": "your_jwt_token_here"
  }'

或从 JavaScript 使用 fetch 和可读流（该端点仅支持 POST，因此仅支持 GET 的原生 EventSource 无法使用）：

const response = await fetch("https://your-domain.com/api/react", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    q: "Hello",
    token: "fim_your_api_key_here"
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  // Parse SSE events from chunk
  console.log(chunk);
}

令牌刷新

访问令牌在 2 小时后过期。使用刷新令牌获取新的访问令牌，无需重新登录：

curl -X POST https://your-domain.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "your_refresh_token_here"
  }'

安全最佳实践

API 密钥

永远不要将 API 密钥提交到版本控制。 它们提供对您数据的完全访问权限。

存储在环境变量中:

export FIM_API_KEY="fim_your_api_key_here"

然后在代码中引用:

api_key = os.environ.get("FIM_API_KEY")

使用密钥轮换:
- 创建新密钥
- 更新您的应用程序
- 删除旧密钥
- 每季度重复一次
设置过期日期:
- 为临时集成使用短期密钥
- 定期要求重新身份验证
使用作用域密钥:
- 除非必要，否则不要使用”完全访问”密钥
- 为不同的服务创建单独的密钥
- 限制密钥泄露时的损害
监控使用情况:
- 检查”最后使用”时间戳
- 查看请求计数
- 删除未使用的密钥

JWT 令牌

保持短生命周期：访问令牌在 2 小时后过期
安全存储：
- 在浏览器中：使用 HttpOnly cookies（比 localStorage 更安全）
- 在服务器中：使用安全的会话存储
不要在日志中暴露：仅记录令牌前缀，不记录完整令牌
仅使用 HTTPS：不要通过未加密的连接发送令牌

速率限制

计划在未来版本中实现按密钥的速率限制。目前没有强制执行的按密钥请求限制。

故障排除

无效令牌错误

{
  "error": "invalid_token",
  "message": "The provided token is invalid or expired"
}

原因:

API 密钥前缀错误（必须以 fim_ 开头）
JWT 令牌已过期（刷新它）
令牌格式错误或已损坏
API 密钥已被删除

解决方案: 验证令牌格式并在必要时重新生成

未授权错误

{
  "error": "unauthorized",
  "message": "Authentication required"
}

原因:

未提供授权标头
请求体中缺少令牌（对于 SSE 端点）
API 密钥已禁用

解决方案: 在每个请求中包含有效的令牌

禁止错误

{
  "error": "forbidden",
  "message": "Your API key does not have permission to access this resource"
}

原因:

API 密钥具有作用域访问权限，缺少所需的作用域
用户账户具有受限权限

解决方案: 使用具有适当作用域的密钥或提高密钥权限

过期的令牌

{
  "error": "token_expired",
  "message": "Your token has expired. Please refresh your authentication."
}

解决方案：使用刷新令牌获取新的访问令牌：

curl -X POST https://your-domain.com/api/auth/refresh \
  -d '{"refresh_token": "your_refresh_token"}'

环境变量设置

Python

import os
from dotenv import load_dotenv
import requests

# Load from .env file
load_dotenv()

api_key = os.getenv("FIM_API_KEY")
base_url = os.getenv("FIM_API_BASE_URL", "https://your-domain.com/api")

headers = {"Authorization": f"Bearer {api_key}"}

# Now use in requests
response = requests.get(f"{base_url}/agents", headers=headers)

Node.js

const api_key = process.env.FIM_API_KEY;
const base_url = process.env.FIM_API_BASE_URL || "https://your-domain.com/api";

const headers = {
  "Authorization": `Bearer ${api_key}`,
  "Content-Type": "application/json"
};

// Use in fetch
const response = await fetch(`${base_url}/agents`, {
  headers: headers
});

Bash

#!/bin/bash

FIM_API_KEY="${FIM_API_KEY:-$(cat ~/.fim_api_key)}"
FIM_API_BASE_URL="${FIM_API_BASE_URL:-https://your-domain.com/api}"

curl -H "Authorization: Bearer $FIM_API_KEY" \
  "$FIM_API_BASE_URL/agents"

支持

如有身份验证问题：

查看 API 概览了解响应格式详情
使用 GET /api/auth/verify 检查令牌过期情况
如果您认为密钥已被泄露，请联系支持

​概述

​API 密钥

​创建 API 密钥

​使用 API 密钥

​API 密钥功能

​作用域

​JWT 令牌

​获取 JWT Token

​使用 JWT 进行流式传输

​令牌刷新

​安全最佳实践

​API 密钥

​JWT 令牌

​速率限制

​故障排除

​无效令牌错误

​未授权错误

​禁止错误

​过期的令牌

​环境变量设置

​Python

​Node.js

​Bash

​支持

概述

API 密钥

创建 API 密钥

使用 API 密钥

API 密钥功能

作用域

JWT 令牌

获取 JWT Token

使用 JWT 进行流式传输

令牌刷新

安全最佳实践

API 密钥

JWT 令牌

速率限制

故障排除

无效令牌错误

未授权错误

禁止错误

过期的令牌

环境变量设置

Python

Node.js

Bash

支持