OAuth 2.0 Authorization Code Flow with PKCE

Introduction

OAuth 2.0 is an industry-standard authorization protocol that allows for greater control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. To enable OAuth 2.0 in your App, you must enable it in your’s App’s authentication settings found in the App settings section of the Developer Console.

How long will my credentials stay valid?

By default, the access token you create through the Authorization Code Flow with PKCE will only stay valid for two hours unless you’ve used the offline.access scope.

Refresh tokens

Refresh tokens allow an application to obtain a new access token without prompting the user via the refresh token flow. If the scope offline.access is applied an OAuth 2.0 refresh token will be issued. With this refresh token, you obtain an access token. If this scope is not passed, we will not generate a refresh token. An example of the request you would make to use a refresh token to obtain a new access token is as follows:

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

App settings

You can select your App’s authentication settings to be OAuth 1.0a or OAuth 2.0. You can also enable an App to access both OAuth 1.0a and OAuth 2.0. OAuth 2.0 can be used with the X API v2 only. If you have selected OAuth 2.0 you will be able to see a Client ID in your App’s Keys and Tokens section.

Confidential Clients

Confidential clients can hold credentials in a secure way without exposing them to unauthorized parties and securely authenticate with the authorization server they keep your client secret safe. Public clients as they’re usually running in a browser or on a mobile device and are unable to use your client secrets. If you select a type of App that is a confidential client, you will be provided with a client secret. If you selected a type of client that is a confidential client in the Developer Console, you will also be able to see a Client Secret. Your options are Native App, Single page App, Web App, Automated App, or bot. Native App and Single page Apps are public clients and Web App and Automated App or bots are confidential clients. You don’t need client id for confidential clients with a valid Authorization Header. You still are required to include Client Id in the body for the requests with a public client.

Scopes

Scopes allow you to set granular access for your App so that your App only has the permissions that it needs. To learn more about what scopes map to what endpoints, view our authentication mapping guide.


Scope	Description
tweet.read	All the Tweets you can view, including Tweets from protected accounts.
tweet.write	Tweet and Retweet for you.
tweet.moderate.write	Hide and unhide replies to your Tweets.
users.email	Email from an authenticated user.
users.read	Any account you can view, including protected accounts.
follows.read	People who follow you and people who you follow.
follows.write	Follow and unfollow people for you.
offline.access	Stay connected to your account until you revoke access.
space.read	All the Spaces you can view.
mute.read	Accounts you’ve muted.
mute.write	Mute and unmute accounts for you.
like.read	Tweets you’ve liked and likes you can view.
like.write	Like and un-like Tweets for you.
list.read	Lists, list members, and list followers of lists you’ve created or are a member of, including private lists.
list.write	Create and manage Lists for you.
block.read	Accounts you’ve blocked.
block.write	Block and unblock accounts for you.
bookmark.read	Get Bookmarked Tweets from an authenticated user.
bookmark.write	Bookmark and remove Bookmarks from Tweets.
dm.read	All the Direct Messages you can view, including Direct Messages from protected accounts.
dm.write	Send and manage Direct Messages for you.
media.write	Upload media.

Rate limits

For the most part, the rate limits are the same as they are authenticating with OAuth 1.0a, with the exception of Tweets lookup and Users lookup. We are increasing the per-App limit from 300 to 900 requests per 15 minutes while using OAuth 2.0 for Tweet lookup and user lookup. To learn more be sure to check out our documentation on rate limits.

Grant types

We only provide authorization code with PKCE and refresh token as the supported grant types for this initial launch. We may provide more grant types in the future.

OAuth 2.0 Flow

OAuth 2.0 uses a similar flow to what we are currently using for OAuth 1.0a. You can check out a diagram and detailed explanation in our documentation on this subject.

Glossary


Term	Description
Grant types	The OAuth framework specifies several grant types for different use cases and a framework for creating new grant types. Examples include authorization code, client credentials, device code, and refresh token.
Confidential client	Clients are applications that can securely authenticate with the authorization server, for example, keeping their registered client secret safe.
Public client	Clients cannot use registered client secrets, such as applications running in a browser or mobile device.
Authorization code flow	Used by both confidential and public clients to exchange an authorization code for an access token.
PKCE	An extension to the authorization code flow to prevent several attacks and to be able to perform the OAuth exchange from public clients securely.
Client ID	Can be found in the keys and tokens section of the Developer Console under the header “Client ID.” If you don’t see this, please get in touch with our team directly. The Client ID will be needed to generate the authorize URL.
Redirect URI	Your callback URL. You will need to have exact match validation.
Authorization code	This allows an application to hit APIs on behalf of users. Known as the auth_code. The auth_code has a time limit of 30 seconds once the App owner receives an approved auth_code from the user. You will have to exchange it with an access token within 30 seconds, or the auth_code will expire.
Access token	Access tokens are the token that applications use to make API requests on behalf of a user.
Refresh token	Allows an application to obtain a new access token without prompting the user via the refresh token flow.
Client Secret	If you have selected an App type that is a confidential client you will be provided with a “Client Secret” under “Client ID” in your App’s keys and tokens section.

Parameters

To construct an OAuth 2.0 authorize URL, you will need to ensure you have the following parameters in the authorization URL.


Parameter	Description
response_type	You will need to specify that this is a code with the word “code”.
client_id	Can be found in the Developer Console under the header “Client ID”.
redirect_uri	Your callback URL. This value must correspond to one of the Callback URLs defined in your App’s settings. For OAuth 2.0, you will need to have exact match validation for your callback URL.
state	A random string you provide to verify against CSRF attacks. The length of this string can be up to 500 characters.
code_challenge	A PKCE parameter, a random secret for each request you make.
code_challenge_method	Specifies the method you are using to make a request (S256 OR plain).

Authorize URL

With OAuth 2.0, you create an authorize URL, which you can use to allow a user to authenticate via an authentication flow, similar to “Sign In” with X. An example of the URL you are creating is as follows:

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

You will need to have the proper encoding for this URL to work, be sure to check out our documentation on the percent encoding.