Why do I need to authenticate?
In order to make calls against the MOO API, we need to know which application is making the calls for tracking, and security purposes. Previously, the MOO API required 3-legged authentication to make calls as the pack data was held on a user's session, but this requirement no longer exists. You can simply make 2-legged OAuth signed calls (AKA signed fetch). The customer no longer needs to grant access before being able to see your application at work! Once you redirect a customer's browser to one of the drop-in URLs returned by an API call they will take ownership of the Pack, at which point the API user can no longer access it.
//This example assumes you're using the OAuth
//module - http://php.net/oauth
$consumerKey = "<YOUR CONSUMER KEY>";
$consumerSecret = "<YOUR CONSUMER SECRET>";
$oauthClient = new OAuth($consumerKey, $consumerSecret);
//We don't need a 3-legged access token
//Make a pack
"method" => "moo.pack.createPack",
"product" => "businesscard"
$createPackResponse = $oauthClient->getLastResponse();
The MOO API uses the OAuth protocol, but for most calls (and in particular all the moo.pack calls) we only require signed calls, rather than 3-legged calls with user access tokens.
"OAuth allows customers to keep their MOO user name and passwords private and not share them with a partner site."
More formally, OAuth authentication is the process by which "users" grant a "consumer" access to a "service provider" "resource" without disclosing their "service provider" account details to the "consumer". Some definitions may help make this clearer!
- A "service provider" would be for example, the MOO web site
- A "resource" is what the "service provider" provides (creating packs, adding to cart etc.). For the MOO API, the resource is the customer's session.
- A "user" is a person who already has an account with the "service provider".
- A "consumer" (a partner site) wants to access the "resources" on the "service provider" web site for the "user"
Simply put, for a partner web site to use the MOO API they must first obtain permission from a user with a MOO account. The user can decide to authorise or deny permission. See below for how OAuth works for "users" and "consumers".
OAuth for Users
For calls which require the user to grant access to their MOO account to the calling application, the process by which users grant the consumer permission to access the service providers resources is called authorisation. When a user selects a function on a consumer web site that uses the MOO API, the user will be directed to the MOO web site. If they are not logged in, then they must do so. They are then presented a page with the following message and "Deny" and "Allow" buttons:
Example Application (www.example.com) would like to have access to your MOO account. You can choose to Deny or Allow this access.
By selecting "Allow", the user grants permission to the consumer to access the service providers resources, which basically means that the partner site can now use the MOO API to make calls against the user's account. At this point, there are no calls which require 3-legged authentication.
OAuth for Consumers
Consumers must first register for credentials. See registration. Once registered, the consumer must use the OAuth authentication protocol flow to obtain authorisation from the user and receive an access token. Only API method calls signed with this access token are permitted.
Direct Access / Two-legged OAuth
Direct access or 'Two-legged' OAuth dispenses with the need for request and access tokens by directly verifying the signature of requests based on the consumer credentials of 'Consumer Key' and 'Consumer Secret'. This is the model that almost all MOO API calls should follow as they don't need access to a user's account. Here, the consumer and user are the same entity. Unlike delegated authorisation or 'Three-legged OAuth', users do not authorise access on an individual basis.
Delegated Authorisation / Three-legged OAuth
Delegated authorisation or 'Three-legged' OAuth is the protocol where the three parties of user, consumer and service provider are involved. The work-flow is described below. An excellent guide to the OAuth protocol can be found here.
OAuth Authentication URLs - only required for 3-legged authorisation
- https://secure.moo.com/oauth/request_token.php - this is the endpoint which is used by your application to get a request token which can then be authenticated. You must provide an oauth_callback url.
- https://secure.moo.com/oauth/authorize.php - this is the URL that users should be directed to, along with the request token, allowing them to allow or deny access to their MOO data
- https://secure.moo.com/oauth/access_token.php - this URL is used by your service to exchange the authorised request token for an access token that will allow access