Twitter API Best Practices: Single vs. Multiple User OAuth

This guest post comes from Adam Green, a Twitter API consultant who Builds custom Twitter apps for clients, and blogs about Twitter programming at Follow him at @140dev.

Twitter's OAuth system is an essential part of using the API, but there are two distinct models for OAuth and good reasons for using one over the other in certain situations. The simplest way to perform an API call with OAuth is called single-user, and it is done by creating a new app at, and requesting a set of user access keys for that app. With these keys the single user will be the Twitter account that owns the app. A more complex method is to allow multiple users to authorize your app to work with their account, and then store a unique set of OAuth keys for each user. You will then be able perform API calls using each set of user keys. Choosing the best of these two programming models depends on a lot of factors:

Rate Limits

This is one of the major reasons for going with multi-user OAuth. Each Twitter account is allowed to make 350 API calls per hour, so if you do single-user OAuth that is your application limit. With multi-user, you can make 350 API calls per hour per user. If just 100 users authorize your app, you will be able to make 35,000 calls per hour! These calls can be used for any API Function that reads data from any account. You are not limited to just the account that gave you the OAuth keys. For example, you can do 35,000 requests for user profiles with users/lookup, which would give you 350,000 profiles. This is not taking away anything from the authorizing user. The 350 calls per hour limit is available to each app a user authorizes. Twitter keeps separate rate limit counts for each app/user combination.

Account Modification

If you need to perform API operations that change an account, such as sending tweets or adding followers, mutli-user OAuth is required. You can only modify a Twitter account with keys for that account. This means that need to stay within the 350 calls per hour limit.

Coding Complexity

Building a working system that does the multi-user "OAuth Dance" is not trivial. This isn't helped by Twitter's Documentation on this subject, which is only useful after you already understand how it works. The other complication is Twitter's lack of internally developed client libraries. You have no choice but to use a third party OAuth Library, and since these libraries are free, the authors have no motivation to provide support. Like lots of programming tasks, multi-user OAuth is not hard to do, but it sure is hard to learn. Single-user Oauth clearly wins in this category. You just copy a set of user keys for the app into your code and make the API Request.

User Interface Complexity

There is no user interface needed for single-user OAuth, everything is done within a server script, so this is another win on complexity. Adding multi-user OAuth to a website means that you have to find a way to ask for authorization by users that doesn't scare them. This is usually done by making this your account creation and login system. Rather than asking explicitly for a user to authorize you to modify their account, you typically offer to let the user "log in with Twitter." As part of that login you also get a copy of the user OAuth keys. The simplest approach is to treat each user who logs in as an account on your site. This eliminates the need for a separate registration process, but this model must be integrated into your site design.

Database Requirement

Once you get a set of OAuth keys for multiple users, you need to be able to store them long-term and retrieve them quickly. Oauth keys are permanent, unless the user revokes your app's authorization, so you will want a reliable storage model. While a flat text file might for a few sets of keys, you will probably want to have a database available for this, which raises the memory and server load requirement for your app. When doing single-user OAuth, you can just paste the keys into a script and include that in any code that needs to call the API.

Error Handling

Error handling is always an interesting part of Twitter API programming, especially when their servers start accidentally returning the wrong error codes. Multi-user Oauth coding requires you to test for a much large set of possible errors. The user's keys will fail if their account is deleted, suspended, and in some cases when it is made into a protected account. I wish I could provide a definitive set of codes for each of these conditions, but they change too often. You can be fairly sure they will be in the 400 range, except when the API gets confused and returns error codes in the 500 range. Single-user is more reliable in this case, since you are controlling the underlying account.


Accepting OAuth keys from users means that you are taking on a heavy responsibility. With their keys you can basically do whatever you want in their account: tweeting, DMing, following, changing their avatar and bio, etc. You do not want to get hacked when doing multi-user OAuth. There are many possible security models, all of which are beyond the scope of this article. A brief description of the model I prefer is to assign cookies to each user with a unique, hash generated key. I never pass the actual keys back to the browser or store them in user cookies. I always confirm that the user making a request that will modify their account is a holder of valid cookies that allow me to look up their OAuth keys on a secure server.

Potential of "Deprecation"

I just love the programmer term "deprecated." It is so Nixonian. Kids, ask your parents about Nixon. The Twitter API is "evolving", another presidential idiom. Anyway. Be aware that if you build a site and app around user authorization there is a chance that Twitter will deprecate this system. They have already split the authorization model once to allow more control on the part of the user, and that could certainly happen again. If you do have to go through this type of transition, all of your users will have to authorize your app again. With single-user OAuth, you will be able to perform this change yourself.


It's clear that complexity is the major disadvantage of multi-user OAuth, but if you need high rate limits or the ability to modify an account, this is your only path. I try to always start an app using single-user OAuth when building a proof of concept version, and then only migrate to multi-user if it is obvious that the production system will require it.

Photos by Hil and Tarik Browne.

Be sure to read the next Best Practices article: Flexible and Collaborative API Design and Documentation with