OAuth Authorization Flow

Sign Up and Get a Consumer Key

Before you can start making Yahoo! API requests, you need to sign up and submit some details about your application.

During registration, indicate the kinds of Yahoo! User data (also called Scopes) you want to access. Later in the OAuth process, Yahoo! will ask your Users if Yahoo! Should allow you to access their User data. For more information about Scopes, see Scopes section in this document.

To sign up, register your application. After registering your application, you will receive a Consumer Key (also called the API Key) which identifies you to Yahoo!. You will also receive a Consumer Secret (also known as the Shared Secret) that will be required when asking for an Request Token. Save the Consumer Key and Secret so that you can use it into your code as required.

Caution

When you sign up for a Consumer Key, be aware that the scopes (permissions) are embedded within the Consumer Key and cannot be changed. If you change the scopes for a particular application, Yahoo! issues a new Consumer Key.

Get a Request Token (get_request_token)

URL:

https://api.login.yahoo.com/oauth/v2/get_request_token

Supported Methods:

GET, POST

Before your Users get involved, your application uses your Consumer Key to obtain a Request Token (OAuth Core 1.0 Spec, Section 6.1).The Request Token is a temporary token used to initiate User authorization for your application. The Request Token tells Yahoo! that you've obtained User approval, but must be exchanged, along with the OAuth Verifier, for an Access Token. The Request Token is intentionally short so that a User can type it manually as part of the redirect URL in cases where the application cannot launch a browser (such as a mobile phone app or a device that has no browser).

The following is an example of URI request for a request token:

The key request parameters are shown in the following table:

Table 2. Request Token (get_request_token) Request Parameters

Request Parameter	Description
`oauth_consumer_key`	Consumer Key provided to you when you signed up.
`oauth_nonce`	A random string (OAuth Core 1.0 Spec, Section 8)
`oauth_signature_method`	The signature method that you use to sign the request. This can be PLAINTEXT or HMAC-SHA1.
`oauth_signature`	The Consumer Secret that was issued to the application. If you are using the PLAINTEXT signature method, add `%26` at the end of the Consumer Secret. For more information about signing requests, refer to Signing Requests to Yahoo!.
`oauth_timestamp`	Current timestamp of the request. This value must be +-600 seconds of the current time.
`oauth_version`	OAuth version (1.0).
`xoauth_lang_pref`	(optional) The language preference of the User; the default value is `EN-US`. For further details about this parameter, refer to the OAuth Extension for Specifying User Language Preference.
`oauth_callback`	Yahoo! redirects Users to this URL after they authorize access to their private data. If your application does not have access to a browser, you must specify the callback as `oob` (out of bounds).

Tip

Because all OAuth requests to Yahoo! login servers are made over HTTPS, you have the choice of using PLAINTEXT or HMAC-SHA1. However, calls made to actual Yahoo! APIs are sent insecurely over HTTP and thus require HMAC-SHA1 signatures.

Yahoo! returns a response similar to the following via the URL:

The key response parameters include the following:

Table 3. Request Token (get_request_token) Response Parameters

Response Parameter	Description
`oauth_token_secret`	This secret associated with the Request Token, provided in hexstring format.
`oauth_expires_in`	The lifetime of the Request Token in seconds. The default number is 3600 seconds, or one hour.
`xoauth_request_auth_url`	The URL to the Yahoo! authorization page.
`oauth_token`	The Request Token that Yahoo! returns as a response to the `request_token` call. The Request Token is required during the User authorization process.
`oauth_callback_confirmed=true`	This parameter confirms that you are using OAuth 1.0 Rev. A. This parameter is always set to true.

Get User Authorization (request_auth)

URL:

https://api.login.yahoo.com/oauth/v2/request_auth

Supported Methods:

GET, POST

After getting the Request Token from Yahoo!, your application presents to your Users a Yahoo! authorization page (OAuth Core 1.0 Spec, Section 6.2) asking them to give permission to your application to access their data.

The authorization page will only ask for permission to a limited amount of User data, based on the access scopes you specified during the initial registration process.

The following is an example of a authorization URL that includes the Request Token:

https://api.login.yahoo.com/oauth/v2/request_auth?oauth_token=j5nyp6

Table 4. Request Auth (request_auth) Request Parameters

Request Parameter	Description
`oauth_token`	The Request Token that Yahoo! returns as a response to the `request_token` call. The Request Token is required during the User authorization process.

The following parameters are appended to the callback URL, if one is provided in Step 2:

Table 5. Request Auth (request_auth) Callback URL Parameters

Callback URL Parameter Description

oauth_token The Request Token that Yahoo! returns as a response to the get_request_token call. It is appended to the authorization page URL. The Request Token is required during the User authorization process.

oauth_verifier The OAuth Verifier is a verification code tied to the Request Token. The OAuth Verifier and Request Token both must be provided in exchange for an Access Token. They also both expire together. If the oauth_callback is set to oob in Step 2, the OAuth Verifier is not included as a response parameter and is instead presented once the User grants authorization to your application. Yahoo! instructs the User to enter the OAuth Verifier code in your application. Your application must ask for this OAuth Verifier code to ensure OAuth authorization can proceed. The OAuth Verifier is intentionally short so that a User can type it manually.

Callback URL Parameter	Description
`oauth_token`	The Request Token that Yahoo! returns as a response to the `get_request_token` call. It is appended to the authorization page URL. The Request Token is required during the User authorization process.
`oauth_verifier`	The OAuth Verifier is a verification code tied to the Request Token. The OAuth Verifier and Request Token both must be provided in exchange for an Access Token. They also both expire together. If the `oauth_callback` is set to `oob` in Step 2, the OAuth Verifier is not included as a response parameter and is instead presented once the User grants authorization to your application. Yahoo! instructs the User to enter the OAuth Verifier code in your application. Your application must ask for this OAuth Verifier code to ensure OAuth authorization can proceed. The OAuth Verifier is intentionally short so that a User can type it manually.

Presenting the Yahoo! Authorization Page

You have two methods for presenting the Yahoo! authorization page:

Present the Yahoo! authorization page through a browser pop-up window. (Preferred Method)
When using the pop-up window method, you must follow these guidelines:
- Your application must open a pop-up window to show the URL provided in xoauth_request_auth_url.
- The pop-up must show the page URL. This is to ensure that Users know they are not being spoofed.
- Once the User has authorized access and Yahoo! redirects the pop-up window to the URL specified in oauth_callback, passing the OAuth Verifier (oauth_verifier).
- After Yahoo! performs the redirect within the pop-up window, your application must exchange the OAuth Verifer along with the Request Token for an Access Token.
- Once you have received an Access Token from Yahoo!, you must close the pop-up window.
The following example uses the Yahoo! Social API PHP SDK to open a pop-up window, listen for an authorization, close the popup, and refresh the originating page:

<?php // Include the YOS library. require("Yahoo.inc"); // Make sure you obtain application keys before continuing by visiting: // https://developer.yahoo.com/dashboard/createKey.html // Your consumer key goes here. define("CONSUMER_KEY",""); // Your consumer key secret goes here. define("CONSUMER_SECRET",""); // Your application ID goes here. define("APP_ID",""); if(array_key_exists("logout", $_GET)) { // if a session exists and the logout flag is detected // clear the session tokens and reload the page. YahooSession::clearSession(); header("Location: sampleapp.php"); } // check for the existance of a session. // this will determine if we need to show a pop-up and fetch // the auth url, or fetch the user's social data. $hasSession = YahooSession::hasSession(CONSUMER_KEY, CONSUMER_SECRET, APP_ID); if($hasSession == FALSE) { // create the callback url, $callback = YahooUtil::current_url()."?in_popup"; // pass the credentials to get an auth url. // this URL will be used for the pop-up. $auth_url = YahooSession::createAuthorizationUrl(CONSUMER_KEY, CONSUMER_SECRET, $callback); } else { // pass the credentials to initiate a session $session = YahooSession::requireSession(CONSUMER_KEY, CONSUMER_SECRET, APP_ID); // if the in_popup flag is detected, // the pop-up has loaded the callback_url and we can close // this window. if(array_key_exists("in_popup", $_GET)) { close_popup(); exit; } // if a session is initialized, fetch the user's profile // information if($session) { // Get the currently sessioned user. $user = $session->getSessionedUser(); // Load the profile for the current user. $profile = $user->getProfile(); } } /** * Helper method to close the pop-up window via javascript. */ function close_popup() { ?> <script type="text/javascript"> window.close(); </script> <?php } ?> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <html> <head> <title>Yahoo! Social Sample Application</title>  <script type="text/javascript" src="http://yui.yahooapis.com/combo?2.7.0/build/yahoo-dom-event/yahoo-dom-event.js"></script> <script type="text/javascript" src="popupmanager.js"></script>  <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/combo?2.7.0/build/reset-fonts-grids/reset-fonts-grids.css&2.7.0/build/base/base-min.css"> </head> <body> <?php if($hasSession == FALSE) { // if a session does not exist, output the // login / share button linked to the auth_url. echo sprintf("<a href=\"%s\" id=\"yloginLink\"><img src=\"http://l.yimg.com/a/i/ydn/social/updt-spurp.png\"></a>\n", $auth_url); } else if($hasSession && $profile) { // if a session does exist and the profile data was // fetched without error, print out a simple usercard. echo sprintf("<img src=\"%s\"/><p><h2>Hi <a href=\"%s\" target=\"_blank\">%s!</a></h2></p>\n", $profile->image->imageUrl, $profile->profileUrl, $profile->nickname); if($profile->status->message != "") { $statusDate = date('F j, y, g:i a', strtotime($profile->status->lastStatusModified)); echo sprintf("<p><strong>“</strong>%s<strong>”</strong> on %s</p>", $profile->status->message, $statusDate); } echo "<p><a href=\"?logout\">Logout</a></p>"; } ?> <script type="text/javascript"> var Event = YAHOO.util.Event; var _gel = function(el) {return document.getElementById(el)}; function handleDOMReady() { if(_gel("yloginLink")) { Event.addListener("yloginLink", "click", handleLoginClick); } } function handleLoginClick(event) { // block the url from opening like normal Event.preventDefault(event); // open pop-up using the auth_url var auth_url = _gel("yloginLink").href; PopupManager.open(auth_url,600,435); } Event.onDOMReady(handleDOMReady); </script> </body> </html>
Redirect from your Web application off-site to the Yahoo! authorization page.
With this method, you must directs Users off-site to the Yahoo authorization page as indicated in xoauth_request_auth_url. Once the User authorizes access, Yahoo! redirects Users to the URL as indicated in oauth_callback.

Note

Because the Yahoo! authorization page is meant to be shown as a pop-up window, it will appear centered and constrained within a full browser window.

Important

If your application does not have access to a browser, it must provide the User with the Yahoo! authorization page URL and Request Token, both provided in Step 2. Your application must provide directions for your User to manually browser to the URL and enter the provided Request Token.

Exchange the Request Token and OAuth Verifier for an Access Token (get_token)

URL:

https://api.login.yahoo.com/oauth/v2/get_token

Supported Methods:

GET, POST

After your Users authorize your application access to their information, your application needs to exchange the approved Request Token for an Access Token, which tells Yahoo! that your application has been given authorization to access User data. (OAuth Core 1.0 Spec, Section 6.3)

The following is an example of a URI request for an Access Token:

Table 6. Get Access Token (get_token) Request Parameters

Request Parameter	Description
`oauth_consumer_key`	Consumer Key provided to you when you signed up.
`oauth_signature_method`	The signature method that you use to sign the request. This can be PLAINTEXT or HMAC-SHA1.
`oauth_nonce`	A random string (OAuth Core 1.0 Spec, Section 8)
`oauth_signature`	The Consumer Secret that was issued to the application. If you are using the PLAINTEXT signature method, add `%26` at the end of the Consumer Secret. If using HMAC-SHA1, refer to OAuth Core 1.0 Spec, Section 9.2. For more information about signing requests, refer to Signing Requests to Yahoo!.
`oauth_timestamp`	Current timestamp of the request. This value must be +-600 seconds of the current time.
`oauth_verifier`	The OAuth Verifier is a verification code tied to the Request Token.
`oauth_version`	OAuth version (1.0).
`oauth_token`	The Request Token, which is required during the User authorization process and is short enough for the end User to easily enter. The Request Token is provided in the response to the `get_request_token` request.

Yahoo! will return a response similar to the following:

Table 7. Get Access Token (get_token) Response Parameters

Response Parameter	Description
`oauth_token`	The Access Token provides access to protected resources accessible through Yahoo! Web services.
`oauth_token_secret`	The secret associated with the Access Token provided in hexstring format.
`oauth_session_handle`	The persistent credential used by Yahoo! to identify the Consumer after a User has authorized access to private data. Include this credential in your request to refresh the Access Token once it expires.
`oauth_expires_in`	Lifetime of the Access Token in seconds (3600, or 1 hour).
`oauth_authorization_expires_in`	Lifetime of the `oauth_session_handle` in seconds.
`xoauth_yahoo_guid`	The introspective GUID of the currently logged in User. For more information of the GUID, see the Yahoo! Social API Reference.

Once you have an Access Token, you can use it towards requests to Yahoo! Web services. For more information on using the Access Token in Yahoo! API requests, refer to Use OAuth in Yahoo! API Requests.

Important

If you used the pop-up window method for presenting the Yahoo! authorization page, ensure that you close this window once you receive the Access Token from Yahoo!.

Refresh the Access Token (get_token)

URL:

https://api.login.yahoo.com/oauth/v2/get_token

Supported Methods:

GET, POST

You can use the Access Token for one hour until it expires. To get a new Access Token for continued use, use the same expired token and the get_token call to be provided a new Access Token. (OAuth Session 1.0 Draft 1, Section 4)

The call looks similar to this:

Table 8. Refresh Access Token (get_token) Request Parameters

Request Parameter	Description
`oauth_nonce`	A random string (OAuth Core 1.0 Spec, Section 8)
`oauth_consumer_key`	Consumer Key provided to you when you sign up on the registration page.
`oauth_signature_method`	The signature method that you use to sign the request. This can be PLAINTEXT or HMAC-SHA1.
`oauth_signature`	The concatenated Consumer Secret and Token Secret separated by an "&" character. For more information about signing requests, refer to Signing Requests to Yahoo!.
`oauth_timestamp`	Current timestamp of the request. This value must be +-600 seconds of the current time.
`oauth_version`	OAuth version (1.0).
`oauth_token`	The expired Access Token.
`oauth_session_handle`	The persistent credential used by Yahoo! to identify the Consumer after a User has authorized access to private data. Include this credential in your request to refresh the Access Token once it expires.

The response to refreshing an Access Token is identical to the original request.

Caution

The Consumer Secret, Access Token Secret, and Session Handle Should be treated as private data on your Web server.