OAuth API 参考索引

OAuth 1.0a


目的	方法
三方（3-legged）OAuth 流程与“使用 X 登录”的第 1 步允许 Consumer 应用获取 OAuth Request Token，以请求用户授权。	POST oauth/request_token
三方（3-legged）OAuth 流程与“使用 X 登录”的第 2 步允许 Consumer 应用使用 OAuth Request Token 请求用户授权。	GET oauth/authenticate
三方（3-legged）OAuth 流程与“使用 X 登录”的第 2 步允许 Consumer 应用使用 OAuth Request Token 请求用户授权。	GET oauth/authorize
三方（3-legged）OAuth 流程与“使用 X 登录”的第 3 步允许 Consumer 应用将 OAuth Request Token 交换为 OAuth Access Token。	POST oauth/access_token
允许已注册的应用吊销已签发的 OAuth Access Token。	POST oauth/invalidate_token

OAuth 2.0 持有者令牌


目的	方法
允许已注册的应用生成 OAuth 2 仅限应用的持有者令牌，可在无用户上下文的情况下代表应用发起 API 请求。	POST oauth2/token
允许已注册的应用撤销已发放的 OAuth 2 仅限应用的持有者令牌。	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`。我们要求与此端点配合使用的任何回调 URL 都必须先在 developer.x.com 的应用设置中配置。	`http://themattharris.local/auth.php` `twitterclient://callback`
x_auth_access_type	可选	覆盖应用请求对用户账户的访问级别。支持的取值为 `read` 或 `write`。此参数旨在使开发者可注册读/写应用，但在合适情况下仅请求只读访问。

在此页面了解如何批准你的回调 URL。 请注意 - 若你已在 developer.x.com 登录 X 账户，可通过 X 应用仪表板查看并编辑你现有的 X 应用。 示例请求 请求 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"

响应：

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 登录”设置。 Resource URL https://api.x.com/oauth/authenticate Resource Information


Response formats	JSON
Requires authentication?	Yes
Rate limited?	Yes

Parameters


Name	Required	Description	Default Value	Example
force_login	optional	强制用户输入其凭据，以确保授权的是正确的用户账户。		true
screen_name	optional	预填 OAuth 登录页的用户名输入框。

Example request 在网页浏览器中将用户导向 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 值；如果使用带外（out-of-band）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 被作废，后续新建的访问令牌将与原令牌不同，且已作废的令牌将不再可用。 资源 URL https://api.x.com/1.1/oauth/invalidate_token 资源信息


响应格式	JSON
是否需要认证？	是 — 使用包含待作废访问令牌的用户上下文
是否受速率限制？	是

示例请求

        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 需要授权
        ...

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

POST oauth2/token

允许已注册的应用获取 OAuth 2 Bearer Token，可在无用户上下文的情况下代表应用自身发起 API 请求。这称为仅应用认证。可使用 oauth2/invalidate_token 使 Bearer Token 失效。一旦 Bearer Token 被作废，新的创建尝试将产生不同的 Bearer Token，且先前令牌将不再可用。每个应用在同一时间只能存在一个有效的 Bearer Token；在其被作废之前，对此方法的重复请求将返回相同的已存在令牌。成功的响应包含一个描述所授予 Bearer Token 的 JSON 结构。通过此方法获得的令牌应予以缓存。若尝试过于频繁，请求将以 HTTP 403 且错误代码为 99 的形式被拒绝。 资源 URL https://api.x.com/oauth2/token 资源信息


响应格式	JSON
是否需要认证？	是 - 使用基础认证，API key 作为用户名，API key secret 作为密码
是否受速率限制？	是

参数


名称	必需	描述	默认值	示例
grant_type	required	指定应用请求的授权类型。目前仅允许 client_credentials。更多信息请参见仅应用认证。		client_credentials

示例请求

    POST /oauth2/token HTTP/1.1
    Host: api.x.com
    User-Agent: 我的 X 应用 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 令牌。令牌一旦失效，后续新建将生成不同的 Bearer 令牌，且被作废的令牌将无法再使用。成功的响应会返回一个描述被撤销 Bearer 令牌的 JSON 结构。 资源 URL https://api.x.com/oauth2/invalidate_token 资源信息


响应格式	JSON
是否需要认证？	是 - 使用 OAuth 1.0a，并包含应用的 consumer API keys 以及应用所有者的 access token 和 access token secret
是否有速率限制？	是

参数

名称	是否必填	说明
access_token	必填	需要作废的 Bearer 令牌的值

示例请求

        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"'

示例响应

         Status: 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 持有者令牌

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 持有者令牌

​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 持有者令牌

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