使用 OAuth 2.0 授权码流程（PKCE）连接到 endpoint

​

如何使用 OAuth 2.0 授权码流程（PKCE）连接至各个 endpoint

​

如何连接到这些 endpoints

要对用户进行身份验证，您的 App 需要实现授权流程。该流程会将用户引导至 X 上的授权对话框。随后，主站的 X 体验将显示授权对话框，并代表您的 App 处理授权。用户可以选择授权您的 App，或拒绝授权。用户做出选择后，X 会将其重定向回您的 App；如果用户已授权，您可以使用授权代码兑换 access token；如果未授权，则需处理拒绝情况。

​

处理机密客户端

如果你正在与机密客户端配合，你需要使用基本身份验证方案，在向令牌endpoint发起请求时，通过base64编码生成授权头（Authorization header）。

在凭据中，userid 和 password 在一个base64编码的字符串内由一个冒号（”:“）分隔。

示例如下：

-header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='

如果用户代理希望发送 Client ID “Aladdin” 和密码 “open sesame”，则会使用以下请求头字段：

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

要创建基本授权头，你需要对你的 Client ID 和 Client Secret 进行base64编码，这些可以从你的 App 的“Keys and Tokens”页面（位于developer portal内）获取。

​

使用 OAuth 2.0 进行连接的步骤

步骤 1：构建 Authorize URL

你的 App 需要构建一个指向 X 的 authorize URL，声明你的 App 需要授权的 scope。比如，如果你的 App 需要查询 Tweets、用户并管理关注，应请求以下 scope：

tweet.read%20users.read%20follows.read%20follows.write

该 URL 还应包含 code_challenge 和 state 参数，以及其他必需参数。在生产环境中，code_challenge 应使用随机字符串。

步骤 2：GET oauth2/authorize

让用户完成身份验证，并向应用发送授权码。如果你已为 App 启用 OAuth 2.0，你可以在 App 的“Keys and Tokens”页面找到你的 Client ID。

用于重定向用户的示例 URL 如下所示：

https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20follows.read%20follows.write&state=state&code_challenge=challenge&code_challenge_method=plain

包含 offline_access 的示例 URL 如下：

https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20follows.read%20offline.access&state=state&code_challenge=challenge&code_challenge_method=plain

在成功完成身份验证后，您会通过 redirect_uri 收到一个包含 auth_code 参数的请求。您的 App 应验证 state 参数。

来自客户端重定向的示例请求如下：

https://www.example.com/?state=state&code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE

步骤 3：POST oauth2/token - 访问令牌

此时，你可以使用授权代码创建 access token 和刷新令牌（仅在请求了 offline.access 范围时）。你可以向以下 endpoint 发送一个 POST 请求：

https://api.x.com/2/oauth2/token

您需要在请求头中传入 Content-Type: application/x-www-form-urlencoded。此外，请在请求中包含：code、grant_type、client_id、redirect_uri，以及 code_verifier。

以下是针对公共客户端的令牌请求示例：

curl --location --request POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ' \
--data-urlencode 'redirect_uri=https://www.example.com' \
--data-urlencode 'code_verifier=challenge'

以下是一个使用机密客户端的示例：

curl --location --request POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://www.example.com' \
--data-urlencode 'code_verifier=challenge'

步骤 4：连接到 API

现在，您已准备好使用 OAuth 2.0 连接到各个 endpoint。为此，您将像使用Bearer Token 认证时一样发起 API 请求。但这一次，您不是传递 Bearer Token，而是使用上一步生成的 access token。作为响应，您应当看到与所请求 endpoint 相对应的有效负载。此请求对公共客户端和机密客户端均相同。 

您将要发起的请求示例如下：

curl --location --request GET 'https://api.x.com/2/tweets?ids=1261326399320715264,1278347468690915330' \
--header 'Authorization: Bearer Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE'

步骤 5：POST oauth2/token - 刷新令牌

刷新令牌使应用程序无需提示用户即可获取新的 access token。您可以通过向以下 endpoint 发送 POST 请求来创建刷新令牌：https://api.x.com/2/oauth2/token 您需要在请求头中将 Content-Type 设置为 application/x-www-form-urlencoded。此外，还需要传入您的 refresh_token，将 grant_type 设为 refresh_token，并指定 client_id。

此请求适用于公共客户端：

POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ'

以下是一个面向机密客户端的示例：

POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE'\
--data-urlencode 'grant_type=refresh_token'

步骤 6：POST oauth2/revoke - 吊销令牌

撤销令牌会使 access token 或 refresh token 失效。它用于在客户端启用“退出登录”功能，便于清理与授权流程相关、可能已无必要的安全凭证。撤销令牌供 App 撤销令牌使用，而非供用户使用。如果 App 希望以编程方式撤销其已获得的访问权限，你可以通过向以下 URL 发起 POST 请求来创建撤销令牌请求：

https://api.x.com/2/oauth2/revoke

您需要在请求头中传递 Content-Type 为 application/x-www-form-urlencoded，以及您的令牌和 client_id。

在某些情况下，用户可能希望撤销先前授予某个 App 的访问权限。他们可以访问已连接的 App 页面以撤销访问权限。

curl --location --request POST 'https://api.x.com/2/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ'

此请求适用于机密客户端：

curl --location --request POST 'https://api.x.com/2/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'token=Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE'