Scopes (Permissions)
As mentioned earlier, most Yahoo! User data is protected by Scopes (permissions) in addition to OAuth authorization.
A Scope is a permission setting that specifies access to a Yahoo! User's non-public data.
Examples of scopes for the Yahoo! Social APIs are:
- Read/Write Yahoo! Updates
- Read (Shared) Yahoo! Profiles
- Read Yahoo! Contacts
You must specify the Scopes needed by your application when you register the application on the Yahoo! Developer Network (YDN). Later on, the end User must give the application permission to access his or her data. A few other steps are necessary, best explained by an example.
Suppose that your application needs to call the HTTP GET operation on a Usercard Profile. Here is the sequence of events that involve Scopes for this example:
- In the Usercard Profile section of
the Yahoo! Social API Reference, note the entry under the Scopes Required
section:
GET: Read (Shared) Yahoo! Profiles
- To register your application, go to the My Projects page of YDN and click New Application.
- If you are registering an Open Application, select "Read" for "Yahoo! Profiles" on the Permissions tab of the Application Editor.
- If you are registering an OAuth Application, select "Read" for "Yahoo! Profiles" on the Request Key page of YDN.
- Behind the scenes, the Scopes you select for your application are embedded in the Consumer Key.
- In your application source code, specify the Consumer Key.
- When the end User installs your application, the Yahoo! page appears, prompting the User to authorize access to the User's Yahoo! Profile.
- Later on, the end User runs your application, which calls an HTTP GET operation on the Usercard Profile.
- Before the GET operation proceeds, Yahoo! OAuth verifies that the end User has authorized access to the Yahoo! Profile data.
- If the GET operation encounters no other errors, it fetches the data and the HTTP response code is 200 OK.
- If the end User had not authorized access, the response code would be an error: 401 Unauthorized.