Obtaining Access Tokens using 3-legged OAuth flow
To perform actions on behalf of another user, you'll need to obtain their access tokens. Access tokens specify the Twitter account the request is made on behalf of, so for you to obtain these they will need to first grant you access. These tokens do not expire but can be revoked by the user at any time.
Twitter allows you to obtain user access tokens through the 3-legged OAuth flow, which allows your application to obtain an access token and access token secret by redirecting a user to Twitter and having them authorize your application. This flow is almost identical to the flow described in implementing Log 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.
Before you get started, you will need to check your application's permissions and know the consumer keys and callback URL. If you don't have a callback URL or publicly accessible UI, consider using PIN-based authorization, which is intended for applications that cannot access or embed a web browser in order to redirect the user after authorization.
The possible states for the 3-legged sign in interaction are illustrated in the following flowchart:
Overview of the process
At a high level, the 3-Legged OAuth process will:
- Create a request for a consumer application to obtain a request token.
- Have the user authenticate, and send the consumer application a request token.
- Convert the request token into a usable user access token.
In the guide below, you may see different terms referring to the same thing.
- App Key === API Key === Consumer API Key === Consumer Key === Customer Key ===
- App Key Secret === API Secret Key === Consumer Secret === Consumer Key === Customer Key ===
- Callback URL ===
- Request Token ===
- Request Token Secret ===
- Access token === Token === resulting
- Access token secret === Token Secret === resulting
Step 1: POST oauth/request_token
Create a request for a consumer application to obtain a 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 configured within your developer App's settings in the app details page of developer portal.
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_callback_confirmed parameters. Your app should verify that
oauth_callback_confirmed is true and store the other two values for the next steps.
Step 2: GET oauth/authorize
Have the user authenticate, and send the consumer application a request token.
Example URL to redirect user to:
Upon successful authentication, your
callback_url would receive a request containing the
oauth_verifier parameters. Your application should verify that the token matches the request token received in step 1.
Request from client’s redirect:
Step 3: POST oauth/access_token
Convert the request token into a usable 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.
A successful response contains the
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.
Using these credentials for OAuth 1.0a (application-user) required requests
Now you've obtained the user access tokens; you can use them to access certain APIs such as POST statuses/update to create Tweets on the users' behalf.
Sample use case
The standard flow is web-based and uses the 3-legged authorization OAuth flow. The screenshots outlined here are part of a sample that you can view the source of at https://github.com/twitterdev/twauth-web.
At some point in your application, you will want to redirect to Twitter in order to authorize your application. When you redirect to Twitter with the request token, the user will be prompted to authorize your application. Upon authorizing your application, the user will be redirected to the callback URL provided when you generated the request token. You will use this to obtain the permanent access token for this user and store it locally.