跳转到主要内容

​
仅应用认证与 OAuth 2.0 Bearer Token

X 为应用提供以应用自身名义（而非特定用户名义）发起已认证请求的能力。X 的实现基于 Client Credentials Grant 流程的 OAuth 2 规范。 仅应用认证不包含任何用户上下文，是一种由应用以自身名义发起 API 请求的认证方式。该方法适用于仅需对公共信息进行只读访问的开发者。  你可以使用应用的 consumer API keys 进行仅应用认证，或使用一个 App only Access Token（Bearer Token）。这意味着你对 X API 所能发起的请求不得要求已认证用户。 通过仅应用认证，你可以执行如下操作：
  • 拉取用户时间线
  • 访问任意账号的关注与粉丝
  • 访问列表资源
  • 搜索 Tweets
请注意，只有 OAuth 1.0a 或 OAuth 2.0 Authorization Code Flow 带有 PKCE 时，才能以用户名义发起请求。 API 参考 页面说明了使用某个 API 所需的认证方法。若要执行以下操作，你将需要用户认证、用户上下文，以及一个访问令牌：
  • 发布 Tweets 或其他资源
  • 搜索用户
  • 使用任意地理位置相关的 endpoint
  • 访问私信或账号凭据
  • 获取用户的电子邮件地址

​
认证流程

要使用此方法，你需要使用仅 App 访问令牌（也称为 Bearer 令牌）。你可以通过向 POST oauth2/token 端点传递你的 consumer key 和 secret 来生成仅 App 访问令牌（Bearer 令牌）。 仅 App 的认证流程包括以下步骤：
  • 应用将其 consumer key 和 secret 编码为一组特殊编码的凭据。
  • 应用向 POST oauth2/token 端点发起请求，用这些凭据换取仅 App 访问令牌。
  • 在访问 REST API 时，应用使用仅 App 访问令牌进行认证。
由于无需对请求进行签名，此方法比标准的 OAuth 1.0a 模型要简单得多。

​
关于仅应用认证

令牌即密码 请注意，consumer key 与 secret，以及仅应用访问令牌（Bearer Token）本身，都可用于代表应用发起请求。应将这些值视为与密码同等敏感，且不得与不受信任的第三方共享或分发。 必须使用 SSL 所有请求（获取和使用令牌）_必须_使用 HTTPS 端点。请遵循使用 TLS 连接到 X API 中的最佳实践——对端应始终进行验证。 无用户上下文 当使用仅应用认证发起请求时，不存在“当前用户”的概念。因此，诸如 POST statuses/update 之类的端点在仅应用认证下将无法工作。参见使用 OAuth以了解如何代表用户发起请求的更多信息。 速率限制 应用具有两类速率限制池。 使用访问令牌代表用户（即用户上下文）发起的请求，其消耗的速率限制与仅应用认证所使用的限制上下文不同。换言之，代表用户发起的请求不会消耗仅应用认证可用的速率限制，而通过仅应用认证发起的请求也不会消耗基于用户的认证所使用的速率限制。 阅读更多关于API 速率限制的内容，并查看限制。

​
发出仅限应用的请求

步骤 1：对 consumer key 和 secret 进行编码 将应用的 consumer key 和 secret 编码为用于获取 Bearer Token 的一组凭证，步骤如下：
  1. 按照 RFC 1738 对 consumer key 和 consumer secret 进行 URL 编码。请注意，以本文撰写时为准，这实际上不会改变 consumer key 和 secret，但仍应执行此步骤，以防将来这些值的格式发生变化。
  2. 将编码后的 consumer key、一个冒号字符“:”，以及编码后的 consumer secret 拼接为单个字符串。
  3. 对上一步得到的字符串进行 Base64 编码。
下面是一些示例值，展示了该算法的结果。请注意，本页使用的 consumer secret 仅用于测试，不能用于真实请求。
Consumer keyxvz1evFS4wEEPTGEFPHBog
Consumer secretL8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
按 RFC 1738 编码的 consumer

key（无变化）		xvz1evFS4wEEPTGEFPHBog
按 RFC 1738 编码的 consumer

secret（无变化）		L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Bearer Token 凭证xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
以上 Bearer Token 凭证的 Base64 编码:: eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
步骤 2：获取仅限应用的访问令牌（Bearer Token） 需要将第 1 步计算的值，通过向 POST oauth2/token 发起请求，兑换为仅限应用的访问令牌：
  • 请求必须为 HTTP POST。
  • 请求必须包含 Authorization 头，值为 Basic <base64 encoded value from step 1>.
  • 请求必须包含 Content-Type 头，值为 application/x-www-form-urlencoded;charset=UTF-8.
  • 请求正文必须为 grant_type=client_credentials。
示例请求（Authorization 头已换行显示）： 
POST /oauth2/token HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip

grant\_type=client\_credentials
如果请求格式正确，服务器会返回一个 JSON 编码的载荷： 响应示例： 
HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 140

{"token\_type":"bearer","access\_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}
应用应验证返回对象中 token_type 键对应的值是否为 bearer。access_token 键对应的值是仅限应用的访问令牌（Bearer Token）。 请注意，同一时间每个应用仅有一个仅限应用的访问令牌有效。使用相同凭据再次向 /oauth2/token 发起请求将返回相同的令牌，直到该令牌被作废。 步骤 3：使用仅限应用的访问令牌（Bearer Token）对 API 请求进行身份验证 仅限应用的访问令牌（Bearer Token）可用于向支持仅应用身份验证的 API 端点发起请求。要使用应用访问令牌，构造常规的 HTTPS 请求，并包含一个 Authorization 头，其值为 Bearer <base64 bearer token value from step 2>. Signing is not required. 示例请求（Authorization 头已换行显示）： 
GET /1.1/statuses/user\_timeline.json?count=100&screen\_name=twitterapi HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAA
                      AAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Accept-Encoding: gzip
使仅限应用的访问令牌（Bearer Token）失效 如果仅限应用的访问令牌遭到泄露或因任何原因需要失效处理，请调用 POST oauth2/invalidate_token。 示例请求（已对 Authorization 头进行换行显示）： 
POST /oauth2/invalidate_token HTTP/1.1
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
User-Agent: My X App v1.0.23
Host: api.x.com
Accept: */*
Content-Length: 119
Content-Type: application/x-www-form-urlencoded

access_token=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
示例响应： 
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 127
...

{"access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

​
常见错误情况

本节介绍在协商和使用 Bearer Token 时的一些常见错误。请注意，这里未涵盖所有可能的错误响应——请留意未处理的错误代码和响应。 获取或撤销仅应用访问令牌（App only Access Token，Bearer Token）时的无效请求 以下操作将会：
  • 以无效请求获取仅应用访问令牌（Bearer Token）（例如，省略 grant_type=client_credentials）。
  • 使用不正确或已过期的应用凭据获取或撤销仅应用访问令牌（Bearer Token）。
  • 使不正确或已被撤销的仅应用访问令牌（Bearer Token）失效。
  • 在短时间内过于频繁地获取仅应用访问令牌（Bearer Token）。
将导致： 
HTTP/1.1 403 Forbidden
Content-Length: 105
Content-Type: application/json; charset=utf-8
...

{"errors":\[{"code":99,"label":"authenticity\_token\_error","message":"无法验证您的凭据"}\]}

​
API 请求包含无效的仅限应用访问令牌（Bearer Token）

使用不正确或已吊销的访问令牌发起 API 请求将导致： 
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 61
...

{"errors":[{"message":"令牌无效或已过期","code":89}]}

​
在不支持仅 App 身份验证的端点上使用仅 App 访问令牌（Bearer Token）

使用仅 App 访问令牌（Bearer Token）请求需要用户上下文的端点（例如 statuses/home_timeline）将会产生： 
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 91
...

{"errors":[{"message":"您的凭据无权访问此资源","code":220}]}