应用

​

概览

如果你已有应用，可在开发者门户的 App 页面查看、编辑或删除它们。

访问 X API 和 X Ads API 需要一组认证凭证（也称密钥和令牌），你必须在每个请求中携带。根据你所使用的具体端点所要求的认证类型，这些凭证可能有不同形式。

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

• API Key 和 Secret： 本质上是你的应用的用户名和密码。你将使用它们来对需要 OAuth 1.0a 用户上下文的请求进行认证，或生成其他令牌，例如用户 Access Token 或 App Access Token。

• Access Token 和 Secret： 一般而言，Access Token 表示你所代表的用户。通过开发者门户生成的令牌表示拥有该应用的用户。你将使用这些令牌来对需要 OAuth 1.0a 用户上下文的请求进行认证。若要代表其他用户发起请求，你需要使用三方 OAuth 流程以获得其授权。

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

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

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

​

应用与项目

你可以使用应用和项目，按使用场景来组织你在 X Developer Platform 上的工作。在 Free X API 方案下，每个项目可包含一个应用；在基础方案下最多可包含两个应用；在 Pro 方案下最多可包含三个应用。

如果你想访问新的 X API v2 端点，你需要使用隶属于某个项目的应用所提供的密钥和令牌。

如果你有在我们推出项目之前创建的应用，它们会显示在名为“独立版应用”的部分。独立版应用是项目结构之外的应用。如果你将独立版应用关联到某个项目，它随后就可以向 v2 端点发起请求。

​

开发者门户仪表板

您可以访问仪表板来管理与您账号关联的应用。要了解更多，请访问我们关于开发者门户的文档页面。该仪表板可帮助开发者快速、便捷地完成以下任务：

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

​

注册以获取访问权限

如果你已有 X 应用，在登录 developer.x.com 的 X 账号后，可通过 X 的应用仪表板查看并编辑你的应用。请注意，管理此前在 developer.x.com 上创建的所有应用时，你无需另行注册账户。

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

​

机器人账户的“自动化账户”标注

你可以为机器人账户添加“自动化账户”标注，让 X 上的用户明确你的机器人是自动化账户。这些机器人通过 X API 执行预设操作。为机器人添加“自动化账户”标注有助于与你的受众建立信任，提升账号可信度，并与垃圾机器人区分开来。这能帮助 X 上的用户在与机器人互动时更好地理解你的账号目的。

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

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

---

​

应用管理

​

介绍

X 应用仪表板 使开发者可以快速、轻松地执行以下任务：

• 查看你现有的应用和项目以及它们关联的 App ID。
• 创建新项目或独立版应用。
• 删除项目、应用或独立版应用。
• 点击进入某个特定应用的设置以打开该应用的设置。在设置中，你可以查看应用详情、密钥与令牌，以及权限。
• 将你的应用的用户认证设置更新为使用 OAuth 1.0a 或 OAuth 2.0。

注意：

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

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

​

应用设置

​

应用详情

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

OAuth 2.0 和 OAuth 1.0a 是允许用户使用 X 登录你的应用的认证方法。它们也允许你的应用代表已认证用户发起特定请求。你可以为你的应用启用其中一种或两种方法。

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

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

​

密钥与令牌

在项目中的某个应用内，或通过独立版应用，你可以查看、重新生成或撤销以下令牌：

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

请注意 - 如果你希望代表其他用户发起请求（也就是说，不是拥有该应用的用户），你需要使用 OAuth 1.0a 三方 OAuth 流程 或 OAuth 2.0 的 Authorization Code with PKCE 流程 来生成一组用户 Access Token。随后在向 API 发起请求时使用这些特定于该用户的令牌。

​

用户认证设置

你可以将应用的认证设置为 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 应用-用户权限

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

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

​

OAuth 2.0 应用类型

如果你选择 OAuth 2.0 作为用户认证方式，你需要选择要创建的应用类型。可选项包括 Native 应用、Single Page 应用、Web 应用、Automated 应用或 bot。Native 应用和 Single Page 应用属于公共客户端，Web 应用以及 Automated 应用或 bot 属于机密客户端。

机密客户端会与授权服务器进行安全认证，并妥善保管你的客户端密钥（client secret）。公共客户端通常是在浏览器或移动设备上运行的应用，无法使用客户端密钥。如果你选择的应用类型属于机密客户端，我们将向你提供一个客户端密钥。

---

​

应用权限

​

OAuth 1.0a 应用权限

应用权限描述了 OAuth 1.0a 应用与用户之间认证的访问级别。应用权限需在你的 X 应用 设置中按应用进行配置。

共有三个权限级别可用：

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

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

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

建议的做法是仅请求应用或服务所需的用户账号数据的最低访问级别。

​

只读

此权限级别仅授予对 X 资源的读取权限，例如用户的 Tweets、主页时间线和个人资料信息。它不允许读取用户的 Direct Messages，也不允许更新任何元素或对象。

​

读取与写入

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

​

读取、写入和管理私信

此权限级别包含上述所有权限，并额外允许应用代表用户读取、发送和删除私信。

• 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 授权码（PKCE）认证方法使开发者能够代表通过特定登录流程的不同 X 用户发起请求。目前，你可以使用两种流程让用户授权你的应用：

• OAuth 2.0 授权码（PKCE）流程
• OAuth 1.0a 三方 OAuth 流程（以及单独的使用 X 登录流程）

当用户完成这些流程、成功登录并向开发者的应用授权后，需要被重定向到一个网页或位置。这个后续网页或位置称为回调 URL。

为让潜在用户完成上述流程，开发者在向相关认证端点发起请求时必须传递回调 URL。例如，使用 OAuth 1.0a 用户上下文 的开发者在请求 GET oauth/request_token 端点时必须传递 callback_url 参数。类似地，使用 OAuth 2.0 授权码（PKCE） 的开发者在请求 GET oauth2/authorize 端点时必须传递 redirect_uri 参数。

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

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

​

需要注意的事项

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

对查询参数进行 HTTP 编码

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

回调 URL 限制

在 X 应用仪表板中，回调 URL 的数量有 10 条的硬性上限。你在授权流程中添加的参数必须与在应用仪表板的允许列表中添加的回调 URL 完全一致。

如果你希望在回调 URL 中包含与请求相关的特定数据，可以使用 state 参数来存储在用户被重定向后需要包含的数据。可以将数据直接编码进 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 未在开发者门户的应用设置中正确添加，你将收到以下错误消息：

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

HTTP 400

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

故障排查

如果遇到错误，请确认在认证请求中使用的回调 URL 已进行 HTTP 编码，并且与已添加到所用应用允许列表中的回调 URL 之一完全匹配（该应用即你在请求中使用其密钥和令牌的应用）。

---