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 portal.
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 Twitter 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 portal, 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.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 |
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 portal 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 portal 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 Twitter.
An example of the URL you are creating is as follows:
You will need to have the proper encoding for this URL to work, be sure to check out our documentation on the percent encoding.