3-legged authorization
The 3-legged OAuth flow allows your application to obtain an access token by redirecting a user to Twitter and having them authorize your application. This flow is almost identical to the flow described in Implementing Sign in with Twitter, with two exceptions:
- The GET oauth/authorize endpoint is used instead of GET oauth/authenticate
- The user will always be prompted to authorize access to your application, even if access was previously granted.
The possible states for the 3-legged sign in interaction are illustrated in the following flowchart:
Overview of the process:
Find your app details, callback URL, credentials and check the permissions for your applications here:
https://developer.twitter.com/en/apps
Terminology clarification
Client Credentials:
App Key === API Key === Consumer API Key === Consumer Key === Customer Key === oauth_consumer_key
App Key Secret === API Secret Key === Consumer Secret === Consumer Key === Customer Key
Callback URL === oauth_callback
Temporary Credentials:
Request Token === oauth_token
Request Token Secret === oauth_token_secret
oauth_verifier
Token Credentials:
Access token === Token === resulting oauth_token
Access token secret === Token Secret === resulting oauth_token_secret
Walkthrough steps
Step 1: POST oauth / request_token
The only unique parameter in this request is oauth_callback, which must be a URL-encoded version of the URL you wish your user to be redirected to when they complete step 2. The remaining parameters are added by the OAuth signing process.
Please note - Any callback URL that you use with the POST oauth / request_token endpoint will have to be whitelisted within the Twitter app settings in the app details page of developer portal: https://developer.twitter.com/en/apps
Request includes:
oauth_callback="https%3A%2F%2FyourWhitelistedCallbackUrl.com"
oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w"
Your app should examine the HTTP status of the response. Any value other than 200 indicates a failure. The body of the response will contain the oauth_token, oauth_token_secret, and oauth_callback_confirmed parameters. Your app should verify that oauth_callback_confirmed is true and store the other two values for the next steps.
Response includes
oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0
oauth_token_secret=veNRnAWe6inFuo8o2u8SLLZLjolYDmDP7SzL0YfYI
oauth_callback_confirmed=true
Step 2: GET oauth/authorize
Example URL to redirect user to:
https://api.x.com/oauth/authorize?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0
Upon a successful authentication, your callback_url would receive a request containing the oauth_token and oauth_verifier parameters. Your application should verify that the token matches the request token received in step 1.
Request from client’s redirect:
https://yourWhitelistedCallbackUrl.com?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY
Step 3: POST oauth / access_token
Converting the request token to an access token.
To render the request token into a usable access token, your application must make a request to the POST oauth / access_token endpoint, containing the oauth_verifier value obtained in step 2. The request token is also passed in the oauth_token portion of the header, but this will have been added by the signing process.
Request includes:
POST /oauth/access_token
oauth_consumer_key=cChZNFj6T5R0TigYB9yd1w
oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0
oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY
A successful response contains the oauth_token, oauth_token_secret parameters. The token and token secret should be stored and used for future authenticated requests to the Twitter API. To determine the identity of the user, use GET account / verify_credentials.
Response includes:
oauth_token=7588892-kagSNqWge8gB1WwE3plnFsJHAZVfxWD7Vb57p0b4
oauth_token_secret=PbKfYqSryyeKDWz4ebtY3o5ogNLG11WJuZBc9fQrQo
Step 4: Using these credentials for app-user required requests
Example POST statuses/update
Request includes:
POST statuses/update.json
oauth_consumer_key=cChZNFj6T5R0TigYB9yd1w
oauth_token=7588892-kagSNqWge8gB1WwE3plnFsJHAZVfxWD7Vb57p0b4