跳转到内容
spacepost文档

安全与 API 密钥

密钥类型

Section titled “密钥类型”
权限 可执行的操作 适用场景
full_access 所有端点 你自己的工具、CLI、MCP 服务器、管理脚本
sending_access 仅限 POST /emails 和 POST /emails/batch 只负责发信的应用服务器

使用 sending_access 密钥调用任何其他端点，都会返回 401 restricted_api_key（“This API key is restricted to only send emails”）。

限定域名的密钥

Section titled “限定域名的密钥”

sending_access 密钥还可以通过 domain_id 绑定到一个域名。绑定后，它只能使用该域名下的地址发信；其他任何 from 都会返回 401 restricted_api_key。你可以用它为每个产品或客户分配独立的密钥。

api-keys.ts
import { SpacePost } from "@spacepost/node";


const spacepost = new SpacePost();


// A key that can only send, and only from one domain.
const { data: key, error } = await spacepost.apiKeys.create({
  name: "worker-prod",
  permission: "sending_access",
  domainId: "0192e1c4-0000-7000-8000-000000000001",
});
if (error) throw new Error(error.message);
console.log(key.token); // sp_live_..., shown only once


const { data: keys } = await spacepost.apiKeys.list();
console.log(keys?.data.map((k) => `${k.name} ${k.prefix}... ${k.permission}`));


await spacepost.apiKeys.remove(key.id);

name 为 1 到 50 个字符。domain_id 仅允许与 sending_access 一起使用。

密钥如何存储

Section titled “密钥如何存储”
  • 密钥形如 sp_live_ 后跟 32 个随机的 base62 字符。
  • SpacePost 只存储 SHA-256 哈希。完整的密钥仅在创建时显示一次。如果丢失，请创建新密钥。
  • 控制台和 GET /api-keys 会显示前缀（sp_live_ 加 4 个字符）、权限、域名以及 last_used_at。
  • 删除密钥（DELETE /api-keys/{id}）会立即吊销它。

良好习惯

Section titled “良好习惯”
  • 切勿把密钥放进客户端代码、移动应用或公开仓库。API 允许跨域请求只是为了让 API 试用平台能够正常工作；请从你的服务器发送邮件。
  • 每个服务和环境使用一个密钥，并清晰命名（worker-prod、ci-staging）。
  • 优先使用 sending_access，并限定到某个域名。
  • 轮换的方法：创建新密钥并部署，检查旧密钥的 last_used_at，然后删除旧密钥。
  • 把密钥保存在密钥管理器或环境变量中，而不是代码里。
  • 密钥一旦泄露，请立即吊销。如果它被提交到了 GitHub，请视为已泄露。
  • SMTP 使用同一个密钥作为密码。参见 SMTP 中继。

传输

Section titled “传输”

所有流量都使用 TLS。API 通过 https://api.spacepost.dev 提供，SMTP 中继位于 smtp.spacepost.dev:25976，要求在认证前使用 STARTTLS（暂不提供 465 端口上的隐式 TLS）。

其他保护措施：SMTP 认证失败的尝试会按 IP 限流；Webhook 端点和附件 URL 必须解析到公网地址（私有网络会被拒绝）；退订链接按联系人签名。

你的数据存储在哪里

Section titled “你的数据存储在哪里”

SpacePost 由 Studio 404 d.o.o. 运营，这是一家位于斯洛文尼亚的欧盟公司，客户数据保存在欧盟境内：

  • 发信： Amazon SES，位于 AWS eu-central-1（德国法兰克福）。所有域名都从该区域发信。
  • 应用与数据库： API、控制台、Worker 和 Postgres 数据库运行在 Railway 的欧盟区域（荷兰阿姆斯特丹）。
  • 隔离： 每个团队通过自己的 SES 租户发信，因此一个客户的信誉问题不会影响其他客户。
  • 网站和文档是由 Cloudflare 全球网络提供的静态页面；那里不存储任何客户数据。

部分服务商（AWS、Stripe、Railway）是美国公司。它们处理哪些数据、在哪里处理，都列在子处理方列表中（英文）。GDPR 数据处理附录（英文）是服务条款的一部分，服务条款受斯洛文尼亚法律管辖。

报告安全漏洞

Section titled “报告安全漏洞”

请发邮件至 support@spacepost.dev 并附上详细信息。请勿针对其他客户的数据进行测试。