配置你自己的 X API Key - Ayrshare API Documentation

自 2026 年 3 月 31 日起，X 更改了第三方平台访问其 API 的方式。因此，每个通过 Ayrshare 向 X 发布内容的 Ayrshare 账号都必须注册自己的 X 开发者应用，并在每一次请求中使用其 API Key 和 API Secret。这是 X 强制推行的、影响所有第三方工具的平台级变更。

BYO（自带）密钥按平台（账号级别）配置一次，而非按每个客户或子资料配置。 你在自己的 X 账号下创建一个 X 开发者应用，然后同一组 API Key + API Secret 会应用到你 Ayrshare 账号下所有关联 X 的每一个子资料 / 最终用户。如果你使用的是 Business 或 Enterprise 套餐、拥有数百个子资料，你不需要为每个子资料重复此配置。你只需为 X 平台配置一次，然后在每次请求中传入同样的两个 header 即可。

我们对配置流程进行了简化，尽可能降低复杂度，完成整个过程大约不超过 10 分钟。请按下方的分步指南操作，如需帮助，我们的团队随时协助。

第 1 步：创建你的 X 开发者账号

登录开发者控制台

前往 console.x.com 并使用你的 X 账号登录。如需帮助，请参见 X 的入门指南。

完成引导

完成开发者引导流程，并接受 Developer Agreement 与相关政策。

进入控制台

你现在已经进入了 X Developer Console。

第 2 步：创建一个应用

你每个 Ayrshare 账号只需创建一个 X 开发者应用。同一个应用及其 API Key + API Secret 会在你的 Ayrshare 账号下之后关联的每个子资料 / 最终用户之间复用。你不需要为每个客户单独创建新应用。

进入 Apps 页面

在 Developer Console 中进入 Apps。

创建应用

在 App 面板中，点击 Create App（详情见 X 的 App 配置文档）。输入一个应用名称（通常为你的品牌名）。当用户连接他们的 X 账号时，OAuth 授权页面会显示该名称。

Create App button in the X Developer Console

选择环境

在下拉菜单中选择 Production（生产）环境。

关闭初始凭证弹窗

X 会生成若干凭证。忽略这些凭证并关闭该窗口。

第 3 步：配置应用权限

打开你的应用设置

在 “Apps” 下找到新建的应用（如果没有显示，请刷新页面），然后点击该应用查看详情。

App details page in the X Developer Console

在 User authentication settings 下点击 Set up。

User authentication settings, click Set up

设置应用权限

在 App permissions 下，选择 Read and write and Direct message。这是完整功能支持（包括发帖与私信）所必需的。

App permissions set to Read and write and Direct message

设置应用类型

在 Type of App 下，选择 Web App, Automated App or Bot。这是像 Ayrshare 这样的服务端集成的正确选项。

Type of App set to Web App, Automated App or Bot

设置回调地址与网站地址

在 App info 下：

Callback URL： 同时添加下面两个回调地址：
- https://profile.ayrshare.com/social-accounts
- https://app.ayrshare.com/social-accounts
Website URL： https://app.ayrshare.com

请勿跳过此步骤。 OAuth 关联流程需要这些回调地址。当你的最终用户授权 X 连接时，X 会将他们重定向回其中一个 URL 以完成关联流程。如果缺少这些地址，OAuth 流程将失败并返回 403 Callback URL not approved 错误。

App info form with callback URL and website URL filled in

保存你的设置

点击 Save。你可以忽略 OAuth 2.0 弹窗，因为你只会用到 OAuth 1.0 的两个密钥（API Key 和 API Secret）。

重要：请在关联账号之前设置好权限。 你在这里选择的权限决定了你的应用能做什么。如果你在通过 OAuth 关联 X 账号之后再修改权限，就需要重新关联，以便新的 Access Token 继承更新后的权限。

Keys and tokens page showing OAuth 1.0 keys with permission level

请务必妥善保存以下 2 个密钥：

API Key（又名 Consumer Key，X 应用的标识符）
API Secret（又名 Consumer Secret）

你不需要手动生成 Access Token。当你通过 OAuth 关联 X 账号时，Ayrshare 会自动处理这部分。

第 4 步：购买 X API 额度

X 现在采用基于额度（credit）的 API 计费方式，通过开发者控制台购买。

进入计费页面

在 Developer Console 左侧栏点击 Billing → Credits。

Billing Credits page in X Developer Console

购买额度

购买额度（最低 $5，足够支持数百次 API 调用）。每次 API 调用只需一分钱的几分之一，对大多数用户来说成本极低。

Credit purchase page in the X Developer Console

启用自动充值

你可以启用 auto-recharge（自动充值）以避免服务中断，同时通过设置账单周期内可花费的最高金额来管理你的消费上限。

Auto-recharge and spend cap settings in X Developer Console

没有额度时你的 API 调用会失败。 X 的 API 是按使用量付费的。如果你的额度余额为零，所有 API 请求都会返回 402 CreditsDepleted 错误，消息为 “Your enrolled account does not have any credits to fulfill this request.”。这包括发帖、读取推文和用户查询。在测试你的集成前请先充值。完整的 X 定价说明请参见 X API 定价方式。

第 5 步：更新你的 Ayrshare API 调用

在第 3 步中，你已在你自己的 env、config 或密钥管理器中妥善保存了以下 2 项：

API Key（又名 Consumer Key，X 应用的标识符）
API Secret（又名 Consumer Secret）

现在，将你的 X 凭证添加到 Ayrshare API 调用的 header 中。

你的密钥保持私有。 Ayrshare 不会存储你的 API Key 和 API Secret。

Header	值
`X-Twitter-OAuth1-Api-Key`	API Key（Consumer Key）
`X-Twitter-OAuth1-Api-Secret`	API Key Secret（Consumer Secret）

如何判断权限是否配置错误：

如果你的应用权限配置错误，API 请求可能返回 403 Forbidden 错误，消息为：“Your client app is not configured with the appropriate OAuth1 app permissions.”

如果你看到此错误，请在 X Developer Console 中将应用权限更新为 Read and write and Direct message，然后通过 OAuth 重新关联你的 X 账号，以便新的 Access Token 继承更新后的权限。

代码示例

curl -X POST https://api.ayrshare.com/api/post \
  -H "Authorization: Bearer YOUR_AYRSHARE_API_KEY" \
  -H "X-Twitter-OAuth1-Api-Key: your_api_key" \
  -H "X-Twitter-OAuth1-Api-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"post": "Hello from my own X App!", "platforms": ["twitter"]}'

const response = await fetch("https://api.ayrshare.com/api/post", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_AYRSHARE_API_KEY",
    "Content-Type": "application/json",
    "X-Twitter-OAuth1-Api-Key": process.env.X_API_KEY,
    "X-Twitter-OAuth1-Api-Secret": process.env.X_API_SECRET,
  },
  body: JSON.stringify({
    post: "Hello from my own X App!",
    platforms: ["twitter"],
  }),
});

import os
import requests

headers = {
    "Authorization": "Bearer YOUR_AYRSHARE_API_KEY",
    "Content-Type": "application/json",
    "X-Twitter-OAuth1-Api-Key": os.environ["X_API_KEY"],
    "X-Twitter-OAuth1-Api-Secret": os.environ["X_API_SECRET"],
}

response = requests.post(
    "https://api.ayrshare.com/api/post",
    headers=headers,
    json={"post": "Hello from my own X App!", "platforms": ["twitter"]},
)

只要你在所有目标为 X 的请求中都带上 API Key 和 API Secret 这两个 header，你现有的自动化流程和工作流就能继续正常工作。

迁移已有资料（Business & Enterprise）

如果你已经有一些子资料通过 Ayrshare 关联了 X，那么在你切换到 BYO 密钥之后，这些资料需要重新关联 X 账号。这是因为已有的 access token 是在 Ayrshare 的 X 应用下签发的，无法与你自己的 consumer keys 一起使用（OAuth 1.0a 签名与签发该 token 的应用绑定）。

在 generateJWT 中包含你的密钥

将 twitterApiKey 和 twitterApiSecret 添加到你的 generateJWT 请求体中。它们会在被嵌入 JWT 前加密，不会暴露给你的最终用户。

{
  "domain": "your-domain",
  "profileKey": "...",
  "privateKey": "...",
  "twitterApiKey": "YOUR_X_CONSUMER_KEY",
  "twitterApiSecret": "YOUR_X_CONSUMER_SECRET"
}

这是唯一一个把 consumer keys 放到请求体的接口。其他所有 X 请求都使用上文描述的 header。

让用户重新关联 X

在生成包含密钥的 JWT 之后，你的用户需要通过资料关联页面重新连接他们的 X 账号。OAuth 授权界面现在会显示你的应用名称而不是 Ayrshare 的名称。为了简化这个过程，你可以：

通过 Unlink API 以编程方式解除关联，然后让用户重新授权
在 generateJWT 中使用 logout 参数强制重新登录
使用 allowedSocial 在迁移流程中让关联页面只显示 X

在所有 API 调用中持续携带 headers

重新关联后，在每一次 API 调用（发帖、分析、评论等）中都要继续携带 X-Twitter-OAuth1-Api-Key 和 X-Twitter-OAuth1-Api-Secret header。

一旦某个资料在你的 X 应用下重新完成了关联，该资料之后的所有帖子都会使用你的凭证。你可以在 X Developer Console 的 Usage 页面进行验证。

验证你的配置

通过 Ayrshare API 使用新的 header 发起一次测试调用，确认一切正常。/analytics/social 接口是一个不错的轻量级测试，因为它不会创建任何帖子。

X API 定价方式

以前，Ayrshare 会代你承担 X API 的使用费用。在 X 当前的模式下，每个 Ayrshare 客户都需自行维护自己的 X 开发者账号，并直接向 X 支付其应用发起的 API 请求费用。（一个 X 开发者账号对应一个 Ayrshare 账号，而不是每个最终用户一个。所有子资料共享同一个 X 开发者账号和额度余额。） X 的定价采用按使用量付费模式：你在 X Developer Console 中购买额度，API 请求发起时会从中扣除。无需签署合同或订阅。常见操作的费用较低。例如：

操作	大致成本
创建帖子（纯文本）	约 $0.01/条
创建带媒体的帖子	约 $0.02/条（媒体上传和发帖是两个独立请求）
读取帖子	约 $0.005/次
用户查询	约 $0.01/次
发送私信	约 $0.01/条
读取私信事件	约 $0.01/事件
用户互动（关注、点赞等）	约 $0.015/次

以此估算，如果你每月发帖约 100 次，你在 X 上的直接成本大约是 $1；如果都带媒体，则大约每月 $2。

X 的按使用量付费定价目前处于试点阶段。费率可能随时调整，也可能引入新的费用项目。请以 Developer Console 中的最新定价为准。参见 X 的定价信息详解。

我们知道这引入了此前没有的一项成本，我们希望在这方面保持透明。同时，这种模式也带来了在之前共享密钥方案下无法实现的多项优势。

使用自己的 X API Key 的好处

使用你自己的 X API 凭证比之前的共享密钥模式提供了更多的控制与可靠性。这包括：

品牌化的 OAuth 体验： 用户在授权访问 X 时会看到你的应用名称与品牌。
独立的速率限制： 你的 API 使用受你自己的 X 开发者账号限额约束，与其他 Ayrshare 用户彼此独立。你可以在 X Developer Console 中监控用量，并参阅 X API 速率限制文档。
凭证掌控： 你的 API Key 与 API Secret 保存在你自己的 X 开发者账号中。Ayrshare 不会存储你的私密密钥。
可移植性： 由于用户是通过你的 X App 进行认证，整个集成始终处于你的完全掌控之下。
用量可见性： 你的 X Developer Dashboard 会展示 API 请求、速率限制与额度使用情况。

X 是首个采用此模式的平台，但会有更多平台转向”自带 API Key”的方式。我们正将这一能力扩展到整个 Ayrshare，让开发者在所有社交平台上都能享有同样的控制与独立性。

安全性

Ayrshare 不会存储你的 API Key 与 API Secret。
关于通用的安全最佳实践，请参见 X 的认证安全指南。

常见问题

我需要为每个客户 / 子资料都做一次这个配置吗？

不需要。 你只需在自己的 X 账号下创建一个 X 开发者应用，同一组 API Key + API Secret 会在你 Ayrshare 账号下之后关联的每个子资料 / 最终用户之间复用。

X 开发者应用只需创建一次。
每次 Ayrshare API 调用都传入同样的两个 header（X-Twitter-OAuth1-Api-Key 和 X-Twitter-OAuth1-Api-Secret），无论该调用针对哪个子资料。
你的最终用户仍需各自完成 OAuth 关联流程来授权他们自己的 X 账号，但他们不需要自己的 X 开发者应用或 API Key。他们通过你的应用进行连接。
所有子资料共享同一个 X 开发者账号、同一个速率限制以及同一个额度余额。

唯一一次按资料处理密钥的场景是在迁移过程中于 generateJWT 的请求体中传入密钥，但仍然是你的同一对密钥，只是让关联页面能够让最终用户在你的应用下重新完成授权。

X API Key 的要求现在已经生效了吗？

是的。自 2026 年 3 月 31 日起，所有通过 Ayrshare 进行的 X 操作都需要你自己的 X API 凭证。如果你还没有配置 X 开发者账号，请按上述步骤操作。

如果我不给 Ayrshare 添加自己的 X API Key 会怎样？

通过 Ayrshare 向 X 发帖需要你自己的 X API 凭证。缺少有效 BYO 凭证的请求将被拒绝。向其他平台（Instagram、LinkedIn、Facebook、TikTok 等）发帖不受影响。

X API 大概需要多少费用？

X 按每次 API 调用收费。创建一条帖子约 $0.01，读取一条帖子约 $0.005。举例来说，每月发布 100 条帖子大约花费 $1。完整详情请参见 X 的定价页面。

这会改变我的 Ayrshare 订阅价格吗？

不会。你的 Ayrshare 订阅价格保持不变。唯一新增的成本是由 X 通过你的开发者账号直接结算的 X API 使用费。

Ayrshare 会存储我的 X API 凭证吗？

不会。Ayrshare 不会存储你的 API Key 和 API Secret。关于通用的安全最佳实践，请参见 X 的认证安全指南。

我已经有 X 开发者账号了。可以用现有的密钥吗？

可以。你可以使用你现有的 X App，只要它启用了 “Read and write” 权限（若使用私信功能还需 Direct Messages 权限）。你需要从 X Developer Console 的 Keys and tokens 部分获取 API Key（Consumer Key）和 API Secret（Consumer Secret）。通过 OAuth 关联你的 X 账号，然后在你的 Ayrshare API 请求中包含这两个 header。如果你在初次配置之后修改过应用权限，请重新关联 X 账号，以便 Access Token 继承更新后的权限。

X Developer Portal 显示了很多凭证。我实际需要哪几个？

你需要 API Key（Consumer Key）和 API Secret（Consumer Secret）。上方 Header 对照表说明了每一项对应的具体 Ayrshare header。你可以忽略 Client ID、Client Secret、Bearer Token、Access Token 和 Access Token Secret。

'API Key' 和 'Client ID' 有什么区别？

它们是用于不同认证方式的完全不同的凭证：

API Key（也叫 “Consumer Key”）用于 OAuth 1.0a。API Key（Consumer Key）+ API Secret 就是 Ayrshare 所使用的凭证。它支持全部 X 功能，token 永不过期，也无需 refresh 逻辑。
Client ID 用于 OAuth 2.0。Ayrshare 不需要这个。OAuth 2.0 的 token 在短时间后就会过期，还需要管理 refresh token。

对于 Ayrshare，你只需要 API Key 和 API Secret 即可。你可以忽略 Client ID、Client Secret 和 Bearer Token。

为什么使用 OAuth 1.0a 而不是 OAuth 2.0？

OAuth 2.0 的 access token 每 2 小时就会过期，而 X 的 refresh token 是一次性的（每次刷新都会作废旧 token）。这使得在无状态的 BYO 模式下（尤其是对排期帖子）无法实现支持。OAuth 1.0a 的 token 永不过期，支持所有 X 功能，且无需任何 token 管理。

我现有的用户需要重新关联他们的 X 账号吗？

需要。如果你的用户是在你配置 BYO 密钥之前通过 Ayrshare 关联 X 的，那么他们需要重新连接。原有的 access token 是在 Ayrshare 的 X 应用下签发的，无法与你的 consumer keys 一起使用。分步流程请参见上文的迁移已有资料。

这一变更会影响向 Instagram、LinkedIn 或其他平台发帖吗？

不会。该变更只影响向 X 发帖。Ayrshare 中所有其他平台的集成都会照常运行。

通过 RSS/Feed 自动发帖到 X 呢？

不再支持通过 RSS 自动发帖到 X。RSS 订阅源按计划自动运行，但自带 API Key 的模式要求每次 API 请求都携带凭证。因此，RSS 订阅源在发送帖子时无法完成认证。如果你之前使用 RSS 向 X 发帖，我们建议切换到排期帖子，或者使用带上你凭证的直接 API 调用。向其他所有平台的 RSS 自动发帖不受影响。

我为什么会收到 402 "CreditsDepleted" 错误？

这表示你的 X 开发者账号没有可用的 API 额度。前往 console.x.com → Billing → Credits 并购买额度。即使 $5 也足够支持数百次 API 调用。加载额度后重试你的请求。

我为什么会收到 403 "Forbidden: OAuth1 App Permissions" 错误？

你的 Access Token 没有正确的权限。这通常意味着以下两种情况之一：

你的应用权限被设为了 “Read” 而不是 “Read and write”。 在 Developer Console 中打开该应用的 Settings，将其更改为 Read and write and Direct message。
你在关联 X 账号之后修改了权限。 Access Token 会保留创建时的权限。请通过 OAuth 重新关联 X 账号，让新的 token 继承更新后的权限。

如果我在配置过程中需要帮助怎么办？

我们的支持团队乐意提供帮助。如果你在配置过程中有任何问题或遇到障碍，请通过 support@ayrshare.com 联系我们，我们会协助你完成整个流程。

故障排查

我收到关于缺少 header 的 400 错误

请确保你同时发送了两个必需的 header：

X-Twitter-OAuth1-Api-Key
X-Twitter-OAuth1-Api-Secret

如果你看到”配对不匹配”的错误（例如 “You provided Api-Key but not Api-Secret”），说明其中一个缺失。两者始终都必须提供。错误消息会告诉你具体缺少的是哪一个 header。

如果你在尝试关联 X 账号时看到此错误，请确认你已在 X 开发者应用的设置中（Authentication settings > Callback URI / Redirect URL）添加了必需的回调地址：

https://profile.ayrshare.com/social-accounts
https://app.ayrshare.com/social-accounts

请参见上文的回调地址配置步骤。

你的 X 开发者账号没有加载任何 API 额度。前往 console.x.com → Billing → Credits 并购买额度。即使 $5 也足够支持数百次 API 调用。

你的 Access Token 没有正确的权限。这通常意味着：

你的应用权限被设为了 “Read” 而不是 “Read and write”。 在 Developer Console 中打开该应用的 Settings，将其更改为 Read and write and Direct message。
你在关联 X 账号之后修改了权限。 Access Token 会保留创建时的权限。请通过 OAuth 重新关联 X 账号，让新的 token 继承更新后的权限。

需要帮助？

如果你在配置 X API Key 时有任何问题或遇到障碍，我们的工程团队乐意协助。你可以随时通过 support@ayrshare.com 联系我们。

​第 1 步：创建你的 X 开发者账号

​第 2 步：创建一个应用

​第 3 步：配置应用权限

​第 4 步：购买 X API 额度

​第 5 步：更新你的 Ayrshare API 调用

​Header 对照表

​代码示例

​迁移已有资料（Business & Enterprise）

​验证你的配置

​X API 定价方式

​使用自己的 X API Key 的好处

​安全性

​常见问题

​故障排查

​需要帮助？

第 1 步：创建你的 X 开发者账号

第 2 步：创建一个应用

第 3 步：配置应用权限

第 4 步：购买 X API 额度

第 5 步：更新你的 Ayrshare API 调用

Header 对照表

代码示例

迁移已有资料（Business & Enterprise）

验证你的配置

X API 定价方式

使用自己的 X API Key 的好处

安全性

常见问题

故障排查

需要帮助？