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

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: 

https://twitter.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20offline.access&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.

 

Additional resources