所有 NueForm API 请求都需要通过 API 密钥进行身份验证。本指南介绍如何生成密钥、在请求中使用密钥以及保障密钥安全。
API 访问适用于 Pro 计划及以上。如果您使用的是 Entrepreneur（免费）计划，则需要先升级才能生成 API 密钥或发起 API 请求。
生成 API 密钥
创建 API 密钥的步骤：
- 登录您的 NueForm 账户。
- 导航至 个人资料 并打开 开发者 选项卡。
- 点击 创建 API 密钥。
- 为您的密钥取一个描述性名称（例如"生产后端"或"CI 管道"）。
- 立即复制密钥 --- 它只会显示一次。
您的完整 API 密钥仅在创建时显示。NueForm 内部存储的是哈希版本，无法检索原始密钥。如果您丢失了密钥，请撤销该密钥并创建一个新的。
API 密钥格式
NueForm API 密钥遵循统一格式：
nf_<64 个十六进制字符>
每个密钥以前缀 nf_ 开头，后跟 64 个十六进制字符（32 个随机字节）。例如：
nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
在控制面板中，密钥通过前缀（前 11 个字符，如 nf_a1b2c3d4）来区分，无需暴露完整值。
使用您的 API 密钥
在每个请求的 Authorization 头中包含您的 API 密钥，使用 Bearer 方案：
Authorization: Bearer nf_your_api_key_here
cURL
curl -X GET https://app.nueform.com/api/v1/forms \
-H "Authorization: Bearer nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
-H "Content-Type: application/json"
JavaScript (fetch)
const NUEFORM_API_KEY = process.env.NUEFORM_API_KEY;
const response = await fetch("https://app.nueform.com/api/v1/forms", {
method: "GET",
headers: {
"Authorization": `Bearer ${NUEFORM_API_KEY}`,
"Content-Type": "application/json",
},
});
const { data } = await response.json();
console.log(data);
Python (requests)
import os
import requests
api_key = os.environ["NUEFORM_API_KEY"]
response = requests.get(
"https://app.nueform.com/api/v1/forms",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
)
data = response.json()["data"]
print(data)
身份验证错误
如果身份验证失败，API 将返回 401 Unauthorized 响应，并附带描述性消息：
| 场景 | 错误消息 |
|---|---|
缺少 Authorization 头 | Missing Authorization header. Use: Authorization: Bearer nf_... |
| 头格式错误 | Invalid Authorization header format. Use: Authorization: Bearer nf_... |
密钥不以 nf_ 开头 | Invalid API key format. Keys must start with "nf_". |
| 密钥已撤销、过期或无效 | Invalid or expired API key. |
| 账户已停用 | Account deactivated. |
| 计划不包含 API 访问 | API access is not available on your current plan. |
错误响应示例：
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired API key.",
"status": 401
}
}
密钥管理
数量限制
每个 NueForm 账户最多可拥有 10 个活跃 API 密钥。如果需要创建新密钥但已达到上限，请先撤销一个已有密钥。
撤销密钥
您可以随时在个人资料的 开发者 选项卡中撤销 API 密钥。撤销立即生效 --- 使用已撤销密钥的任何请求都将收到 401 Unauthorized 响应。
撤销密钥的步骤：
- 前往 个人资料 > 开发者。
- 找到要撤销的密钥（通过名称和前缀识别）。
- 点击 撤销。
- 确认操作。
撤销密钥的操作无法撤消。使用该密钥的任何服务或集成将立即失去访问权限。请确保在撤销旧密钥之前，使用新密钥更新您的应用程序。
最后使用跟踪
NueForm 会跟踪每个 API 密钥的最后使用时间。查看 开发者 选项卡，了解哪些密钥正在使用中，哪些可以安全撤销。
计划要求
API 访问是一项需要付费计划的功能：
| 计划 | API 访问 | 速率限制 |
|---|---|---|
| Entrepreneur（免费） | 否 | --- |
| Pro（$29/月） | 是 | 100 请求/分钟 |
| Enterprise（$99/月） | 是 | 500 请求/分钟 |
如果您尝试在不包含 API 访问的计划账户上使用 API 密钥，将收到 403 Forbidden 响应：
{
"error": {
"code": "FORBIDDEN",
"message": "API access is not available on your current plan.",
"status": 403
}
}
安全最佳实践
遵循以下准则保障您的 API 密钥安全：
切勿将密钥提交到版本控制
将密钥文件添加到 .gitignore 并使用环境变量代替。如果密钥被意外提交，请立即撤销并生成新密钥。
# .env（将 .env 添加到您的 .gitignore）
NUEFORM_API_KEY=nf_your_api_key_here
使用环境变量
在每个环境中（本地开发、预发布和生产）都将 API 密钥存储在环境变量中。切勿将密钥硬编码到应用程序源代码中。
// 正确做法
const apiKey = process.env.NUEFORM_API_KEY;
// 错误做法 --- 切勿这样做
const apiKey = "nf_a1b2c3d4...";
为每个环境使用不同密钥
为开发、预发布和生产环境创建不同的 API 密钥。这样可以在密钥泄露时限制影响范围，并且方便撤销单个环境的访问权限。
定期轮换密钥
定期创建新密钥并逐步淘汰旧密钥。NueForm 允许最多 10 个活跃密钥，因此您可以创建新密钥、更新服务、验证一切正常后再撤销旧密钥。
仅限服务器端使用
API 密钥只应在服务器端代码中使用。切勿在客户端 JavaScript、移动应用或任何在用户浏览器中运行的代码中暴露您的 API 密钥。
切勿在前端代码、公开仓库或客户端请求中包含您的 API 密钥。泄露的密钥将允许对您的账户进行完全 API 访问。如果您怀疑密钥已泄露，请立即撤销。