OAuth API 参考索引

OAuth 1.0a


Purpose	Method
三方 OAuth 授权流程的第 1 步及“使用 X 登录” 允许消费者应用获取 OAuth Request Token，以请求用户授权。	POST oauth/request_token
三方 OAuth 授权流程的第 2 步及“使用 X 登录” 允许消费者应用使用 OAuth Request Token 请求用户授权。	GET oauth/authenticate
三方 OAuth 授权流程的第 2 步及“使用 X 登录” 允许消费者应用使用 OAuth Request Token 请求用户授权。	GET oauth/authorize
三方 OAuth 授权流程的第 3 步及“使用 X 登录” 允许消费者应用将 OAuth Request Token 交换为 OAuth 访问令牌。	POST oauth/access_token
允许已注册的应用撤销已签发的 OAuth 访问令牌。	POST oauth/invalidate_token

OAuth 2.0 Bearer Token


Purpose	Method
允许已注册的 App 生成 OAuth 2 仅限应用模式的 OAuth 2.0 Bearer Token，可在无用户上下文的情况下代表 App 发起 API 请求。	POST oauth2/token
允许已注册的 App 吊销已签发的 OAuth 2 仅限应用模式的 OAuth 2.0 Bearer Token。	POST oauth2/invalidate_token

POST oauth/request_token

允许 Consumer 应用获取 OAuth Request Token 以请求用户授权。此方法符合 OAuth 1.0 身份验证流程的第 6.1 节。 我们要求你在所有 OAuth 授权步骤中使用 HTTPS。 使用说明： oauth_nonce 仅接受 ASCII 值 资源 URL https://api.x.com/oauth/request_token 资源信息


响应格式	JSON
需要身份验证？	否
有请求速率限制？	是

参数

名称	必填	描述	示例
oauth_callback	必填	为符合 OAuth 1.0a，此参数为必填。你在此处指定的值将作为用户在批准你的应用访问其账号后被重定向到的 URL。将其设置为 `oob` 以启用带外 PIN 模式。这也是在桌面/移动应用中指定自定义回调的方式。无论是否预先注册了回调，在此步骤务必发送 `oauth_callback`。使用此 endpoint 的任何回调 URL 均必须先在 developer.x.com 的 App 设置中进行配置*	`http://themattharris.local/auth.php` `twitterclient://callback`
x_auth_access_type	可选	覆盖应用向用户账号请求的访问级别。支持的取值为 `read` 或 `write`。该参数用于让开发者可将应用注册为读/写，但在适当情况下仅请求只读访问。

在此页面了解如何批准你的回调 URL。 请注意 - 如果你已在 developer.x.com 上登录你的 X 账号，你可以通过 X app 仪表板查看和编辑你现有的 X apps。 示例请求 请求 URL：POST https://api.x.com/oauth/request_token 请求 POST Body：N/A Authorization Header:

OAuth oauth_nonce="K7ny27JTpKVsTgdyLdDfmQQWVLERj2zAK5BslRsqyw", oauth_callback="http%3A%2F%2Fmyapp.com%3A3005%2Ftwitter%2Fprocess_callback", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1300228849", oauth_consumer_key="OqEqJeafRSF11jBMStrZz", oauth_signature="Pc%2BMLdv028fxCErFyi8KXFM%2BddU%3D", oauth_version="1.0"

Response:

oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik&oauth_token_secret=Kd75W4OQfb2oJTV0vzGzeXftVAwgMnEK9MumzYcM&oauth_callback_confirmed=true

GET oauth/authorize

允许 Consumer 应用使用 OAuth Request Token 请求用户授权。此方法对应 OAuth 1.0 认证流程的第 6.2 节。桌面应用必须使用此方法（且不能使用 GET oauth/authenticate）。 使用说明： 不要将 oauth_callback 发送到此方法，请改为提供给 POST oauth/request_token。 资源 URL https://api.x.com/oauth/authorize 资源信息


响应格式	JSON
需要认证？	是
有请求速率限制？	是

参数


名称	必填	描述	默认值	示例
force_login	可选	强制用户输入其凭据，以确保授权的是正确的用户账户。
screen_name	可选	以给定值预填 OAuth 登录页的用户名输入框。

示例请求 在网页浏览器中将用户导向 oauth/authorize 步骤，并包含一个 oauth_token 参数： https://api.x.com/oauth/authorize?oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik

GET oauth/authenticate

允许 Consumer 应用使用 OAuth 的 request_token 发起用户授权请求。对于使用回调式认证流程的应用，此方法替代了 OAuth 1.0 认证流程中的第 6.2 节。除非将 force_login 参数设为 true，否则该方法将以当前已登录用户作为进行访问授权的账户。此方法与 GET oauth/authorize 的不同在于：如果用户已向该应用授予权限，将直接重定向，而无需用户再次批准。要实现此行为，你必须在应用记录中启用“使用 X 登录”设置。 资源 URL https://api.x.com/oauth/authenticate 资源信息


响应格式	JSON
是否需要认证？	是
是否有请求速率限制？	是

参数


名称	是否必需	描述	默认值	示例
force_login	可选	强制用户输入其凭据，确保授权到正确的用户账户。		true
screen_name	可选	以给定值预填 OAuth 登录页面的用户名输入框。

示例请求 在网页浏览器中将用户引导至 oauth/authenticate 步骤，并包含 oauth_token 参数： https://api.x.com/oauth/authenticate?oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik

POST oauth/access_token

允许 Consumer 应用将 OAuth Request Token 交换为 OAuth Access Token。此方法对应 OAuth 1.0 身份验证流程的第 6.3 节。 资源 URL https://api.x.com/oauth/access_token 资源信息


响应格式	JSON
是否需要认证？	是
是否有请求速率限制？	是

参数


名称	是否必填	描述	默认值	示例
oauth_token	required	此处的 oauth_token 必须与 request_token 步骤中返回的 oauth_token 相同。
oauth_verifier	required	如果使用 OAuth 网页流程，将此参数设置为回调 URL 中返回的 oauth_verifier 的值；如果使用带外 OAuth，请将此值设置为 PIN 码。为符合 OAuth 1.0a，此参数为必填。OAuth 1.0a 将被严格执行，未使用 oauth_verifier 的应用将无法完成 OAuth 流程。

示例请求

POST https://api.x.com/oauth/access_token?oauth_token=qLBVyoAAAAAAx72QAAATZxQWU6P&oauth_verifier=ghLM8lYmAxDbaqL912RZSRjCCEXKDIzx

基于 PIN 的 POST https://api.x.com/oauth/access_token?oauth_token=9Npq8AAAAAAAx72QBRABZ4DAfY9&oauth_verifier=4868795 示例响应

oauth_token=6253282-eWudHldSbIaelX7swmsiHImEL4KinwaGloHANdrY&oauth_token_secret=2EEfA6BG5ly3sR3XjE0IBSnlQu4ZrUzPiYTmrkVU&user_id=6253282&screen_name=xapi

POST oauth/invalidate_token

允许已注册的应用通过提供其客户端凭据来撤销已签发的 OAuth access_token。一旦某个 access_token 被作废，后续创建将生成不同的 access token，且不再允许使用已作废的令牌。 资源 URL https://api.x.com/1.1/oauth/invalidate_token 资源信息


响应格式	JSON
是否需要身份验证？	是 - 使用你希望作废的 access token 的用户上下文
是否有请求速率限制？	是

示例请求

        curl --request POST
          --url 'https://api.x.com/1.1/oauth/invalidate_token.json'
          --header 'authorization: OAuth oauth_consumer_key="CLIENT_KEY",
         oauth_nonce="AUTO_GENERATED_NONCE", oauth_signature="AUTO_GENERATED_SIGNATURE",
         oauth_signature_method="HMAC-SHA1", oauth_timestamp="AUTO_GENERATED_TIMESTAMP",
         oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

示例响应

        HTTP/1.1 200 OK
        Content-Type: application/json; charset=utf-8
        Content-Length: 127
        ...

        {"access_token":"ACCESS_TOKEN"}

令牌失效后的错误响应示例

        HTTP/1.1 401 Authorization Required
        ...

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

POST oauth2/token

允许已注册的应用获取 OAuth 2 Bearer Token，可在无用户上下文的情况下代表应用自身发起 API 请求。这称为仅应用身份验证。可使用 oauth2/invalidate_token 使 Bearer Token 失效。一旦 Bearer Token 被作废，后续创建将产生不同的 Bearer Token，且先前令牌将不再可用。每个应用在任意时刻仅能拥有一个有效的 Bearer Token；在其失效之前，对该方法的重复请求将返回相同的现有令牌。成功的响应包含一个 JSON 结构，描述所颁发的 Bearer Token。通过此方法获得的令牌应当缓存。若请求过于频繁，将以 HTTP 403 且 code 99 被拒绝。 Resource URL https://api.x.com/oauth2/token Resource Information


Response formats	JSON
Requires authentication?	是 - 使用 Basic auth，将你的 API Key 作为用户名、API Key Secret 作为密码
Rate limited?	是

Parameters


Name	Required	Description	Default Value	Example
grant_type	required	指定应用请求的授权类型。目前仅允许 client_credentials。更多信息请参见仅应用身份验证。		client_credentials

Example request

    POST /oauth2/token HTTP/1.1
    Host: api.x.com
    User-Agent: My X App v1.0.23
    Authorization: Basic eHZ6MWV2R ... o4OERSZHlPZw==
    Content-Type: application/x-www-form-urlencoded;charset=UTF-8
    Content-Length: 29
    Accept-Encoding: gzip

    grant_type=client_credentials

示例响应：

    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":"AAAA%2FAAA%3DAAAAAAAA"}

POST oauth2/invalidate_token

允许已注册的应用通过提供其客户端凭证撤销已签发的 OAuth 2.0 Bearer Token。一旦某个 Bearer Token 被作废，后续新创建将生成不同的 Bearer Token，且已作废的令牌将无法再使用。成功的响应包含一个描述被撤销的 Bearer Token 的 JSON 结构。 Resource URL https://api.x.com/oauth2/invalidate_token Resource Information


Response formats	JSON
Requires authentication?	是 - OAuth 1.0a，使用应用的 consumer API keys 以及应用所有者的 access token 和 access token secret
Rate limited?	是

Parameters

Name	Required	Description
access_token	required	要作废的 bearer token 的值

Example request

        curl --request POST
          --url 'https://api.x.com/oauth2/invalidate_token?access_token=AAAA%2FAAA%3DAAAAAAAA'
          --header 'authorization: OAuth oauth_consumer_key="CLIENT_KEY",
         oauth_nonce="AUTO_GENERATED_NONCE", oauth_signature="AUTO_GENERATED_SIGNATURE",
         oauth_signature_method="HMAC-SHA1", oauth_timestamp="AUTO_GENERATED_TIMESTAMP",
         oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

示例响应

         状态：200 OK
         Content-Type: application/json; charset=utf-8
         Content-Length: 135
         ...
       {
        "access_token": "AAAA%2FAAA%3DAAAAAAAA"
        }

入门

基础

合作伙伴与客户

资源

OAuth API 参考索引

OAuth 1.0a

OAuth 2.0 Bearer Token

POST oauth/request_token

GET oauth/authorize

GET oauth/authenticate

POST oauth/access_token

POST oauth/invalidate_token

POST oauth2/token

POST oauth2/invalidate_token

入门

基础

合作伙伴与客户

资源

​OAuth 1.0a

​OAuth 2.0 Bearer Token

​POST oauth/request_token

​GET oauth/authorize

​GET oauth/authenticate

​POST oauth/access_token

​POST oauth/invalidate_token

​POST oauth2/token

​POST oauth2/invalidate_token

OAuth 1.0a

OAuth 2.0 Bearer Token

POST oauth/request_token

GET oauth/authorize

GET oauth/authenticate

POST oauth/access_token

POST oauth/invalidate_token

POST oauth2/token

POST oauth2/invalidate_token