开发者应用（App）

​

概览

如果你已有 App，可以通过开发者门户网站的 App 页面查看、编辑或删除它们。

访问 X API 和 X Ads API 需要一组身份验证凭据（也称“密钥和令牌”），并且必须随每个请求一同提交。根据你所使用的特定 endpoint 所要求的身份验证类型，这些凭据可能以不同形式出现。

以下是在你的 App 中可生成的不同凭据及其使用方式：

• API Key and Secret： 本质上相当于你的 App 的“用户名”和“密码”。你将使用它们来对需要 OAuth 1.0a 用户上下文的请求进行身份验证，或用于生成其他令牌，例如用户 Access Tokens 或 App Access Token。

• Access Token and Secret： 通常，Access Tokens 代表你所代为发起请求的用户。通过开发者门户网站生成的 Access Tokens 代表拥有该 App 的用户。你将使用这些令牌对需要 OAuth 1.0a 用户上下文的请求进行身份验证。如果你希望代表其他用户发起请求，需要使用三方 OAuth 授权流程以获得他们的授权。

• Client ID and Client Secret： 这些凭据用于通过 OAuth 2.0 身份验证获取用户 Access Token。与 OAuth 1.0a 类似，用户 Access Tokens 用于对提供私有用户账号信息或代表其他账号执行操作的请求进行身份验证；但在 OAuth 2.0 下可通过更细粒度的 scope 更好地控制客户端应用对用户的访问权限。

• App only Access Token： 当向仅返回 X 上公开可用信息的 endpoint 发起请求时，你将使用此令牌。

除了生成发起 X API 请求所需的密钥和令牌外，你还可以设置访问权限、记录该 App 的用例或目的、定义回调 URL，并在管理控制台中修改与你的 App 开发环境相关的其他设置。

​

App 和 Project

您可以使用 App 和 Project，按使用场景组织您在 X Developer Platform 上的工作。使用 Free X API 方案时，每个 Project 可包含一个 App；使用 Basic 方案时最多可包含两个 App；使用 Pro 方案时最多可包含三个 App。

如果您希望访问新的 X API v2 endpoint，则需要使用隶属于某个 Project 的 App 的密钥和令牌。

如果您有在我们推出 Project 之前创建的 App，它们会显示在名为“Standalone Apps”的部分中。Standalone Apps 是位于 Project 结构之外的 App。如果您将 Standalone App 关联到某个 Project，随后即可向 v2 endpoint 发出请求。

​

开发者门户网站仪表板

你可以访问仪表板来管理与你账户关联的 App。要了解更多，请访问我们的开发者门户网站文档页面。该仪表板可帮助开发者快速便捷地执行以下任务：

• 查看你现有的独立 App 及其关联的 App ID。
• 创建新的 Project、App 或独立 App。
• 删除未使用的 Project 或 App。
• 查看或更新特定 App 的设置，包括更新名称、描述、网站、回调 URL 以及权限。
• 重新生成 App 专属凭证，例如 API Key 与 Secret、App Access Token，以及 App 所有者的用户 Access Tokens。

​

注册获取访问权限

如果你已有 X App，并且已在 developer.x.com 上登录你的 X 账号，你可以通过 X 的 App dashboard 查看和编辑你的 App。请注意，你不需要注册新账号即可管理此前在 developer.x.com 上创建的所有 App。

如果你需要创建新的 X App，则必须先注册开发者账号。如果你是团队账号成员，创建新 App 需要被授予管理员角色。

​

机器人账户的 “Automated Account” 标签

你可以为机器账户添加 “Automated Account” 标签，让 X 上的用户知道你的机器人是自动化账户。这些机器人通过 X API 执行预设操作。为机器人添加该标签有助于与受众建立信任、提升账户可信度，并将你的账户与垃圾机器人区分开来。这也有助于 X 上的用户在与机器人交互时更好地理解你的账户用途。

要为机器人账户添加标签，请按以下步骤操作：

1. 前往账户设置
2. 选择 “Your account”
3. 选择 “Automation”
4. 选择 “Managing account”
5. 接着，选择运行你的机器人账户的 X 账户
6. 输入密码登录
7. 最后，你应能看到标签已应用到你的账户的确认信息。

---

​

App 管理

​

简介

X App 仪表板 让开发者能够快速、便捷地完成以下任务：

• 查看你现有的 App 和 Projects 及其关联的 App ID。
• 创建新的 Project 或独立 App。
• 删除 Project、App 或独立 App。
• 点击进入某个特定 App 的设置。在设置中，你可以查看 App 详情、密钥和令牌，以及权限。
• 将你的 App 的用户身份验证设置更新为使用 OAuth 1.0a 或 OAuth 2.0（开放授权 2.0）。

注意：

所有 App 的密钥和令牌在开发者门户网站中已不可见，生成后必须妥善保存。我们建议使用密码管理器来存储你的密钥和令牌。

你可以显示 API Key 提示，以帮助你将凭证与其对应的 App 进行匹配。

​

App 设置

​

App 详情

在此你可以编辑 App 图标、App 名称、App 描述、你的网站 URL、回调 URL/重定向 URI、服务条款 URL、隐私政策 URL、组织名称、组织 URL，以及该 App 的目标或使用场景。

OAuth 2.0（开放授权 2.0）和 OAuth 1.0a 是允许用户通过 X 登录你的 App 的身份验证方法。它们还允许你的 App 代表已认证用户发起特定请求。你可以为 App 启用其中一种或两种方法。

保持这些信息为最新非常重要。你的 App 名称和网站 URL 将作为来源显示在你的应用以编程方式创建的任何 Tweet 的 metadata 中。若你更改了 X App 的使用场景，请务必在这些设置中更新使用场景，以确保遵守开发者条款。

如果你的应用带有“suspended”标签，说明你的应用违反了 X 的一项或多项开发者条款，例如我们的自动化规则。开发者平台政策团队将通过设置在 App 所有者 X 账号上的电子邮件地址与开发者沟通。要查看该电子邮件地址，请查看你的X 账号设置。关于暂停的通知邮件将发送至该邮箱，邮件主题类似于“Application suspension notice”，并包含下一步操作的具体信息。若需与 X 团队合作处理暂停问题，请查收电子邮件以获取具体指示，或使用我们的平台帮助表单。

​

密钥和令牌

在 Project 中的 App 内，或通过独立的 App，您可以查看、重新生成或撤销以下令牌：

• API Key（Consumer Key）和 API Secret（Consumer Secret）
• App Access Token
• User Access Token 和 Access Token Secret - 开发者门户网站中提供的 Access Token 和 Secret 对应于拥有该 App 的用户。

请注意 - 如果您希望代表其他用户发起请求（也就是说，不是拥有该 App 的用户），则必须使用 OAuth 1.0a 三方 OAuth 授权流程 或 OAuth 2.0 的带有 PKCE 的授权码流程 来生成一组用户 Access Tokens。随后，您需在对 API 的请求中使用这些用户特定的令牌。

​

用户身份验证设置

您可以将 App 的身份验证设置为 OAuth 1.0a 或 OAuth 2.0。OAuth 2.0 仅适用于 X API v2。OAuth 2.0 允许您选择更细粒度的 scope，以代表用户获取特定权限。OAuth 1.0a 可用于 X API v1.1 和 v2，并采用较为宽泛的授权与较粗粒度的 scope。

​

OAuth 1.0a 应用—用户权限

如果您是 App 的所有者，您可以调整该 App 的权限（仅读取；读取和写入；或读取、写入和私人讯息）。这将决定您通过 X API 可访问的资源和事件（注意：某些资源需要直接向 X 申请额外权限）。

您还可以在此页面启用或禁用您的 App 请求用户电子邮件地址的功能（这要求在“App details”页面提供服务条款 URL 和隐私政策 URL）。

​

OAuth 2.0 类型的 App

如果你选择 OAuth 2.0 作为用户身份验证方法，你需要同时选择要创建的 App 类型。可选项包括 Native App、Single Page App、Web App、Automated App 或 bot。Native App 和 Single Page App 属于公共客户端，Web App 与 Automated App 或 bot 属于机密客户端。

机密客户端会与授权服务器安全地进行身份验证，并妥善保管你的客户端密钥。公共客户端通常在浏览器或移动设备上运行，无法使用客户端密钥。如果你选择的 App 类型属于机密客户端，你将获得一个客户端密钥。

---

​

App 权限

​

OAuth 1.0a App 权限

App 权限用于描述 OAuth 1.0a 应用-用户认证的访问级别。你可以在 X App 的每个应用设置中配置 App 权限。

可用的权限级别共有三种：

1. 仅读取
2. 读取和写入
3. 读取、写入以及访问私人讯息

另外还有一项附加权限可用于请求查看用户的电子邮件地址——可与上述任一权限级别组合使用。

如果更改了权限级别，任何已签发给该 X App 的用户令牌都必须作废，且用户必须重新授权该 App，令牌才能继承更新后的权限。

最佳实践是仅请求应用或服务所需的用户账户数据的最低访问级别。

​

仅限读取

此权限级别允许对 X 资源进行读取访问，例如用户的 Tweet、主页时间线和个人资料信息。不允许读取用户的私人讯息，也不允许更新任何元素或对象。

​

读取与写入

此权限级别允许对 X 资源进行读取和写入访问。除读取访问外，还允许发布 Tweet、关注用户，或更新用户资料信息。它还允许代表通过身份验证的用户隐藏回复。此权限级别不允许任何对私人讯息的访问（包括读取、写入或 delete）。

​

读取、写入与访问私人讯息

此权限层级包含以上所有权限，并另外允许代表用户读取、写入与删除私人讯息。

• POST /2/dm_conversations/:dm_conversation_id/messages
• POST /2/dm_conversations/
• POST /2/dm_conversations/with/:participant_id/messages
• GET /2/dm_conversations/with/:user_id/dm_events
• GET /2/dm_conversations/:dm_conversation_id/dm_events
• GET /2/dm_events

​

确定权限

所有已通过身份验证的 API 请求都会在 HTTP 响应中返回一个 x-access-level 标头。该标头的值表示当前使用的权限级别。可能的取值包括 read、read-write 和 read-write-directmessages。

---

​

回调 URL

OAuth 1.0a 用户上下文 和 OAuth 2.0 授权码（Authorization Code）配合 PKCE 的身份验证方法，使开发者能够代表已通过特定登录流程的不同 X 用户发起请求。目前，您可以使用以下两种流程来让用户授权您的应用：

• OAuth 2.0 authorization code flow with PKCE
• OAuth 1.0a 3-legged OAuth flow（以及单独的 Sign in with X flow）

当用户按照这些流程进行操作时，他们在成功登录并向开发者的 App 授权后，需要被重定向到一个网页或位置。这个后续网页或位置称为回调 URL。

在为潜在用户配置这些流程时，开发者必须在向上述流程所涉及的身份验证 endpoint 发起请求时传递回调 URL。例如，使用 OAuth 1.0a 用户上下文 的开发者在向 GET oauth/request_token endpoint 发起请求时，必须传递 callback_url 参数。类似地，使用 OAuth 2.0 授权码（Authorization Code）配合 PKCE 的开发者，必须在向 GET oauth2/authorize endpoint 发起请求时传递 redirect_uri 参数。

除了使用这些参数之外，开发者还必须确保已将该回调 URL 添加到其 App 的回调 URL 允许列表中，该列表可在 开发者门户网站 的 App 设置页面找到。

如果配置正确，用户在作为这些流程的一部分成功登录 X 后，将被重定向到回调 URL。

​

需要注意的事项

在设置回调 URL 时，请注意以下几点：

对 query 参数进行 HTTP 编码

由于你会通过 callback_url 或 redirect_uri 参数将回调 URL 作为 query 参数传递，请确保对该 URL 进行 HTTP 编码。

回调 URL 限制

X Apps 仪表板中回调 URL 的数量上限为 10。你的回调 URL 必须与在 Apps 仪表板允许列表中添加的回调 URL，以及你在授权流程中传入的参数值完全匹配。

如果希望在回调 URL 中包含与请求相关的 data，可以使用 state 参数来存储在用户重定向后需要携带的 data。可以将 data 直接编码进 state 参数，或将该参数用作会话 ID，在服务器端存储状态。

不要使用 localhost 作为回调 URL 请不要使用 localhost，请在本地使用自定义主机或 http(s)://127.0.0.1

自定义协议 URL 如果希望利用移动端深度链接，可以使用带有路径和域名部分的自定义协议 URL，例如 twitter://callback/path。不过，我们确实有一份不允许使用的协议列表需要避免。你可以在下方查看该不允许使用的协议列表。

不允许的协议

vbscript	ldap
javascript	mailto
vbs	mmst
data	mmsu
mocha	msbd
keyword	rtsp
livescript	mso-offdap
ftp	snews
file	news
gopher	nntp
acrobat	outlook
callto	stssync
daap	rlogin
itpc	telnet
itms	tn3270
firefoxurl	shell
hcp	sip

​

错误示例

如果你使用的回调 URL 未在开发者门户网站的 App 设置中正确添加，则会收到以下错误消息：

OAuth 1.0a

HTTP 403 - Forbidden

{
  "errors": [
    {
      "code":415,"message":"此客户端应用程序的回调 URL 未获得批准。可在您的应用程序设置中调整已批准的回调 URL。"
    }
  ]
}

或

<?xml version="1.0" encoding="UTF-8"?>
<hash>
<error>此客户端应用程序的回调 URL 未获得批准。已批准的回调 URL 可在您的应用程序设置中进行调整</error>
<request>/oauth/request_token</request>
</hash>

OAuth 2.0（开放授权 2.0）

HTTP 400

{
  "error": "invalid_request",
  "error_description": "传递的重定向 URI 值与授权码的 URI 不匹配。"
}

故障排除

如果您遇到错误，请确保在身份验证请求中使用的回调 URL 已进行 HTTP 编码，并且与您所使用密钥和令牌对应的 App 的允许列表中已添加的某个回调 URL 完全匹配。

---