Enum egg_mode::Token [−] [src]

pub enum Token<'a> {
    Access {
        consumer: KeyPair<'a>,
        access: KeyPair<'a>,
    },
    Bearer(String),
}

A token that can be used to sign requests to Twitter.

Authenticating Requests With Twitter

A Token is given at the end of the authentication process, and is what you use to authenticate every other call you make with Twitter. The process is different depending on whether you're wanting to operate on behalf of a user, and on how easily your application can open a web browser and/or redirect web requests to and from Twitter. For more information, see Twitter's OAuth documentation overview.

The very first thing you'll need to do to get access to the Twitter API is to head to Twitter's Application Manager and create an app. Once you've done that, there are two sets of keys immediately available to you. First are the "consumer key" and "consumer secret", that are used to represent you as the application author when signing requests. These keys are given to every single API call regardless of permission level. Related are an "access token" and "access token secret", that can be used to skip the authentication steps if you're only interacting with your own account or with no account in particular. Generally, if you want to read or write to a particular user's stream, you'll need to request authorization and get an access token to work on their behalf.

Access Tokens

Access tokens are for when you want to perform your requests on behalf of a specific user. This could be for something like posting to their account, reading their home timeline, viewing protected accounts they follow, and other actions that only make sense from the perspective from a specific user. Because of the two-fold nature of making sure your requests are signed from your specific app and from that specific user, the authentication process for access tokens is fairly complicated.

The process to get an access token for a specific user (with this library) has three basic steps:

Log your request with Twitter by getting a request token.
Direct the user to grant permission to your application by sending them to an authenticate or authorize URL, depending on the nature of your app.
Convert the verifier given by the permission request into an access token.

Before you get too deep into the authentication process, it helps to know a couple things about the app you're writing:

Is your app in an environment where directing users to and from a web page is easy? (e.g. a website, or a mobile app)
Are you using Twitter authentication as a substitute for user accounts, instead of just to interact with their Twitter account?

Depending on your answer to the first question, you may need to use "PIN-Based Authorization", where the user completes the authentication/authorization process in a separate window and receives a numeric PIN in response that your app can use to complete the authentication process. The alternative to that is the standard OAuth flow, where a web browser is directed to Twitter to complete the login and authorization, then redirected back to your app to receive the access token proper. The way to signal one method or another is by the callback parameter to the access token request.

The second question informs where you send the user to authorize your app. Using the "Sign In With Twitter" flow, your app could be able to transparently request another access token without the user needing to accept the connection every time. This is ideal for websites where a "Sign In With Twitter" button could replace a regular login button, instead using a user's Twitter account in place for regular username/password credentials. To be able to use the "Sign In With Twitter" flow, you must first enable it for your app on Twitter's Application Manager. Then, for Step 2 of the authentication process, send the user to an authenticate URL.

The primary difference between the different URLs for Step 2 is that an authenticate URL allows the above behavior, whereas an authorize URL does not require the extra setting in the app manager and always requires the user to re-authorize the app every time they're sent through the authentication process. As access tokens can be cached indefinitely until the app's access is revoked, this is not necessarily as onerous as it sounds.

The end result of Step 2 is that your app receives a "verifier" to vouch for the user's acceptance of your app. With PIN-Based Authorization, the user receives a PIN from Twitter that acts as the verifier. With "Sign In With Twitter" and its counterpart, "3-Legged Authorization", the verifier is given as a query parameter to the callback URL given back in Step 1. With this verifier and the original request token, you can combine them with your app's consumer token to get the access token that opens up the rest of the Twitter API.

Example (Access Token)

For "PIN-Based Authorization":

let con_token = egg_mode::KeyPair::new("consumer key", "consumer secret");
// "oob" is needed for PIN-based auth; see docs for `request_token` for more info
let request_token = egg_mode::request_token(&con_token, "oob").unwrap();
let auth_url = egg_mode::authorize_url(&request_token);

// give auth_url to the user, they can sign in to Twitter and accept your app's permissions.
// they'll receive a PIN in return, they need to give this to your application

let verifier = "123456"; //read the PIN from the user here

// note this consumes con_token; if you want to sign in multiple accounts, clone it here
let (token, user_id, screen_name) =
    egg_mode::access_token(con_token, &request_token, verifier).unwrap();

// token can be given to any egg_mode method that asks for a token
// user_id and screen_name refer to the user who signed in

WARNING: The consumer token and preset access token mentioned below are as privileged as passwords! If your consumer key pair leaks or is visible to the public, anyone can impersonate your app! If you use a fixed token for your app, it's recommended to set them in separate files and use include_str!() (from the standard library) to load them in, so you can safely exclude them from source control.

Shortcut: Pre-Generated Access Token

If you only want to sign in as yourself, you can skip the request token authentication flow entirely and instead use the access token key pair given alongside your app keys:

let con_token = egg_mode::KeyPair::new("consumer key", "consumer secret");
let access_token = egg_mode::KeyPair::new("access token key", "access token secret");
let token = egg_mode::Token::Access {
    consumer: con_token,
    access: access_token,
};

// token can be given to any egg_mode method that asks for a token

Bearer Tokens

Bearer tokens are for when you want to perform requests on behalf of your app itself, instead of a specific user. Bearer tokens are the API equivalent of viewing Twitter from a logged-out session. Anything that's already public can be viewed, but things like protected users or the home timeline can't be accessed with bearer tokens. On the other hand, because you don't need to authenticate a user, obtaining a bearer token is relatively simple.

If a Bearer token will work for your purposes, use the following steps to get a Token:

With the consumer key/secret obtained the same way as above, ask Twitter for the current Bearer token for your application.

And... that's it! This Bearer token can be cached and saved for future use. It will not expire until you ask Twitter to invalidate the token for you. Otherwise, this token can be used the same way as the access token from earlier, but with the restrictions mentioned above.

Example (Bearer Token)

let con_token = egg_mode::KeyPair::new("consumer key", "consumer secret");
let token = egg_mode::bearer_token(&con_token).unwrap();

// token can be given to *most* egg_mode methods that ask for a token
// for restrictions, see docs for bearer_token

Variants

Access

An OAuth Access token indicating the request is coming from a specific user.

Fields of `Access`

`consumer: KeyPair<'a>`	A "consumer" key/secret that represents the application sending the request.
`access: KeyPair<'a>`	An "access" key/secret that represents the user's authorization of the application.

Bearer(String)

An OAuth Bearer token indicating the request is coming from the application itself, not a particular user.

Trait Implementations

`impl<'a> Debug for Token<'a>`
[src]

`fn fmt(&self, __arg_0: &mut Formatter) -> Result`

Formats the value using the given formatter.

`impl<'a> Clone for Token<'a>`
[src]

`fn clone(&self) -> Token<'a>`

Returns a copy of the value. Read more

`fn clone_from(&mut self, source: &Self)`
1.0.0

Performs copy-assignment from source. Read more