跳转到主要内容

​
App only 身份验证与 OAuth 2.0 Bearer Token

X 为应用提供以应用自身而非特定用户的身份发起已认证请求的能力。X 的实现基于 OAuth 2 规范 的 Client Credentials Grant 流程。 仅应用身份验证不包含任何用户上下文，是一种应用以自身名义发起 API 请求的身份验证方式。此方法适用于仅需对公开信息进行只读访问的开发者。 你可以使用应用的消费者 API Key 进行仅应用身份验证，或使用 App only Access Token（OAuth 2.0 Bearer Token）。这意味着你对 X API 可发起的请求不得要求经过身份验证的用户。 通过仅应用身份验证，你可以执行以下操作：
  • 拉取用户时间线
  • 访问任意账户的好友与关注者
  • 访问 List 资源
  • 搜索 Tweets
请注意，只有使用带有 PKCE 的 OAuth 1.0a 或 OAuth 2.0 Authorization Code Flow 才能以用户名义发起请求。API reference 页面描述了使用某个 API 所需的身份验证方法。要执行以下操作，你将需要用户身份验证（用户上下文）以及一个 access token：
  • 发布 Tweets 或其他资源
  • 搜索用户
  • 使用任何地理相关 endpoint
  • 访问私信或账户凭据
  • 获取用户的电子邮件地址

​
认证流程

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

​
关于仅应用程序身份验证

令牌即密码 请注意，consumer key 与 secret，以及 App only Access Token（Bearer Token）本身，均可用于代表应用程序发起请求。这些值应与密码同等对待，属高度敏感信息，绝不可与不受信任的第三方共享或分发。 必须使用 SSL 所有请求（无论是获取还是使用令牌）都必须通过 HTTPS endpoint。请遵循使用 TLS 连接到 X API 中的最佳实践——对端应始终进行验证。 无用户上下文 使用仅应用程序身份验证发起请求时，不存在“当前用户”的概念。因此，诸如 POST statuses/update 等 endpoint 无法在仅应用程序身份验证下使用。有关代表用户发起请求的更多信息，请参阅使用 OAuth。 请求速率限制 应用程序有两类请求速率限制池。 使用 access tokens 代表用户发起的请求（也称为用户上下文）会从不同于仅应用程序身份验证的请求速率限制 context 中扣减。换句话说，代表用户发起的请求不会消耗通过 app-only 身份验证可用的请求速率限制，而通过 app-only 身份验证发起的请求也不会消耗用户身份验证所使用的请求速率限制。 了解更多：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
Base64 编码后的 Bearer Token 凭据:: eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
步骤 2：获取 App only Access Token（Bearer Token） 需要将步骤 1 中计算的值通过向 POST oauth2/token 发起请求来交换为 App only Access 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 键对应的值是 App only Access Token（OAuth 2.0 Bearer Token）。 请注意，任一时刻每个应用仅有一个 App only Access Token 有效。使用相同凭据向 /oauth2/token 再次发起请求会返回同一个令牌，直到该令牌被作废。 步骤 3：使用 App only Access Token（OAuth 2.0 Bearer Token）对 API 请求进行认证 App only Access Token（OAuth 2.0 Bearer Token）可用于向支持仅应用认证的 API endpoint 发起请求。要使用 App Access Token，构造一个常规的 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
使 App only Access Token（Bearer Token）失效 如果 App only Access 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"}

​
常见错误情况

本节介绍在协商和使用 OAuth 2.0 Bearer Token 过程中常见的错误。请注意，此处未涵盖所有可能的错误响应——请留意未处理的错误代码和响应。 获取或撤销 App only Access Token 的无效请求 尝试执行以下操作：
  • 使用无效请求获取 App only Access Token (Bearer Token)（例如，省略 grant_type=client_credentials）。
  • 使用不正确或已过期的 App 凭据获取或撤销 App only Access Token (Bearer Token)。
  • 使不正确或已撤销的 App only Access Token (Bearer Token) 失效。
  • 在短时间内过于频繁地获取 App only Access 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 请求包含无效的 App only Access Token（Bearer Token）

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

{"errors":\[{"message":"Invalid or expired token","code":89}\]}

​
在不支持 App only 身份验证的 endpoint 上使用 App only Access Token（Bearer Token）

对需要用户 context 的 endpoint（例如 statuses/home_timeline）使用 App only Access Token（Bearer Token）将会导致： 
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 91
...

{"errors":[{"message":"您的凭据不允许访问此资源","code":220}]}
⌘I