xAuth

About xAuth

xAuth is still OAuth. You still need to master how to send signed requests to Twitter.

The xAuth process will only yield read-only or read-write access tokens. Direct message read access is not provided with xAuth. If your application requires access to a user’s direct messages, you will need to use the full OAuth flow.

xAuth provides a way for desktop and mobile applications to exchange a username and password for an OAuth access token. Once the access token is retrieved, xAuth-enabled developers should dispose of the login and password corresponding to the user.

xAuth access is restricted to approved applications. If your application is a desktop or mobile application that has no other recourse but to utilize xAuth, send a detailed request to https://support.twitter.com/forms/platform. Include the name of your application, the consumer key, the application ID (if available), and a summary of how xAuth is best-suited for your application.

xAuth requires that you use header-based OAuth authentication against an SSL access token end point, using the POST HTTP method.

xAuth also supports Twitter’s Login Verification feature.

Using xAuth

To use xAuth, first request access by filling out this form with plenty of details about your application and why xAuth is the best choice for it. xAuth is only granted in circumstances where the standard OAuth flow is not possible.

xAuth allows desktop and mobile applications to skip the request_token and authorize steps and jump right to the access_token step. See POST oauth / access_token for more details.

To request an Access Token for a browser-less app, make an HTTPS request to the Twitter Access Token URL https://api.twitter.com/oauth/access_token with your application’s consumer key. In addition to the conventional oauth_* signing parameters, the following post parameters must be submitted:

• x_auth_usernamethe login credential of the User the client is obtaining a token on behalf of
• x_auth_passwordthe password credential of the User the client is obtaining a token on behalf of
• x_auth_modethis value must “client_auth” (referring to the process described here)

Example request for an xAuth Access Token

Test Values

The values provided in these examples will fail to validate if actually executed against the Twitter API for a variety of reasons: these keys are no longer valid, the password for the user is different, and the timestamp is now stale. However, utilizing these test values in isolation should yield the same signature when building your implementation.

If we were performing an xAuth Access Token request with the following parameters:

• oauth_consumer_key - JvyS7DO2qd6NNTsXJ4E7zA
• oauth_consumer_secret - 9z6157pUbOBqtbm0A0q4r29Y2EYzIHlUwbF4Cl9c
• oauth_nonce - 6AN2dKRzxyGhmIXUKSmp1JcB4pckM8rD3frKMTmVAo
• oauth_signature_method - HMAC-SHA1
• oauth_timestamp - 1284565601
• oauth_version - 1.0
• x_auth_mode - client_auth
• x_auth_password - twitter-xauth
• x_auth_username - oauth_test_exec

Your HTTP POST body would look like this (note that your POST body should be URL encoded):

x_auth_username=oauth_test_exec&x_auth_password=twitter-xauth&x_auth_mode=client_auth

After properly URL encoding the various elements, your OAuth signature base string would look like this:

Please note how the already URL-escaped POST body gets encoded again in this process.

Because this request does not involve an oauth_token, your signing secret for building your signature is:

9z6157pUbOBqtbm0A0q4r29Y2EYzIHlUwbF4Cl9c&

Your OAuth HTTP Authorization header would appear like this, after signing with the secret:

And upon successful authentication, you would get something like the following response:

From that point forward you would use the access token (and its secret) to sign all authentication-requiring requests. See this page for more insight on where to go from access token acquisition.

Login Verification

If the user is enrolled in login verification, the server will return a HTTP 401 error with a custom body. If you are using the send_error_codes parameter, you will receive the following error message in the response body:

User must verify login

Otherwise, the response body will contain a plaintext response:

User must verify login

When this error occurs, advise the user to generate a temporary password on twitter.com and use that to complete signing in to the application.