The Upcoming REST API has a method by which third party applications can access actual user data by getting automatic authorization from the user to do so, without having to collect a username and password in plaintext. This method is referred to throughout this document as "token-based authentication." The basic interaction works as follows - the third party app can direct users to a special URL on our site, with some extra information identifying which app is contacting us. We make the users log in on our site, and once that user is logged in, they can opt to approve access to their account from your app.
Once the user has logged in and approved your app for access to their account, we send back a special code ("frob") that you can use to obtain a token for access to that user's account. That token will contain the user's information, as well as a special token code that you can pass to us with every method that supports authentication, instead of passing us a username and password directly. In this way, we can both communicate without ever sending a user's password over the wire.
You can currently pick a couple of ways to do the app-to-upcoming communication. The easiest way, described above, requires you to provide us with a callback URL to which we pass the "frob" after the user has authorized your app for access to their account. We also recommend that you provide a name and description for your application, so that we can show it to the user when they are prompted to authorize your app for access.
If you don't provide a callback URL, the user will be shown the frob, and the user will have to copy and paste it into your application. That still requires work for you to provide a form for entry of the frob, but in desktop applications (where no callback URL can be provided), this may be your best choice.
You can set these up on the API Key Generation Page.
The following sections will go into detail about each stage of the process. If you have questions about this, or require additional documentation, please ask on the yws-events discussion group.
The first step is to construct a URL to the auth page, where the user will need to log in and approve your app for access to their account. The URL should be constructed in this format:
http://upcoming.yahoo.com/services/auth/?api_key=<Your API Key>
If a user's already logged in, they will be shown the name and description of your app (that you entered in the API Key Generation Page, right?), and asked if they would like to approve your app for access to their account. Access is not currently fine-grained, so it's either all-or-nothing - if they approve your app for access, then your app will be able to manage and view all of their private account data, as if they were directly logged in to your app. If the user's not yet logged in (or doesn't have an account), they must log in before they can proceed. If they've already logged in, AND there is still a valid frob, then we automatically redirect the user to your callback page, if available, along with a frob that can be used to grab the existing token.
In any case, if your app is then approved, we generate a frob that is valid for 60 minutes from the time of generation. The frob is appended to your callback URL, as ?frob=<Frob Code>, or if you did not provide a callback URL, it is displayed directly to the user for copy and paste.
Once you've got a valid Frob, you can then get the token that will be used to authenticate all method calls to the API that support user auth. You should call the auth.getToken method to get a token from the Frob provided. This sends you back an XML node with the username, user's full name, userid, and the token code to use for method calls.
Once the frob has been used to get a token, subsequent calls to getToken with that frob will produce the token (if unexpired) regardless of whether the frob is expired.
Now that you have the proper token for the user, you may authenticate any method calls that require or support it by including the parameter token in your method calls, either via GET or POST. All methods should accept the token instead of the traditional username and password.
There are a couple of tricky topics that we'll officially address here, so as to avoid confusion as to how the system works.
Currently, all tokens granted last forever. That means once a user uses your app and authorizes it, you can safely store that token forever for that user, and it will remain active until they disapprove of its access (which we do not currently allow). In the future, we may allow for expiration of tokens as a user option. In any case, if your app ever gets a 403: Not Authorized error from our API, you should use auth.checkToken to check for the existence of a token by its code. If the token does not exist, you will have to send the user back to the authentication page for re-authentication.
We have endeavored to only permit one token per user per app at any given time. If you discover this is not the case, it is a bug and may be reported or discussed via the wiki.
As we used to allow direct passing of username and password to our API, we are temporarily still leaving that method for authentication open for backwards compatibility. However, all app developers should move to the Token-based authentication as quickly as possible. It allows for a smoother user experience, and also poses less security risk to your users.