Open topic with navigation

Consumer Authentication

To secure and verify API Consumers, each API call must be authenticated with the following procedure. This procedure uses the OAuth Consumer/Service Provider authentication protocol.

Notes: 

• See http://oauth.net/core/1.0 and http://oauth.net/ for information about OAuth.
• See http://destroytoday.com/blog/2010/02/encoding-for-oauth-using-as3/ for information on using OAuth for AS3 applications.

Requirements

Before you can send requests to Photobucket, you must:

• Get an OAuth Consumer Key (<consumer_key>) and an OAuth Consumer Secret (<consumer_secret>) from developer.photobucket.com.
• Get the current timestamp (<ts>) from your server. This is the seconds since the epoch, GMT (typically time() or Date.now()). The timestamp relies on the hash generator having a clock that is close to correct.

Note: Client computers frequently have clocks that are incorrect. You may need to get the time from an independent source.

• Get a random string per timestamp (<nonce>) to add randomness and prevent replay attacks. This requires a random number generator that is random enough for each request.
• Have the ability to generate HMAC hashes, using the SHA1 algorithm, to generate the request signature. Most languages have libraries available to do this.

Authentication

After you have satisfied the requirements, you can request a page anonymously or request a page as a user.

Notes:

• The signatures DO expire. This timeout is set by Photobucket as needed, so always generate a new signature per request.
• Signed requests are required for EVERY operation.

Requesting a Page Anonymously

Many requests to Photobucket do not require a user to be logged in, such as search or getting public albums. The following process follows the OAuth Consumer Request procedure.

• Use the Photobucket API libraries that are provided, and use the Consumer Key and Consumer Secret as necessary. This signs your request appropriately.
• Use another OAuth request library. (There are a few available from OAuth.net's repository). The request procedure is similar to the "request token" procedure from the OAuth Core specification, so OAuth libraries can use that procedure. Remember that the URL ALWAYS has the hostname "api.photobucket.com", regardless of the actual host being called, to avoid confusion during redirects that may happen.

Signing Process

1. Gather your parameters:

• Your Consumer Key (<consumer_key>) - Received from Photobucket.
• Your Consumer Secret (<consumer_secret>) - Received from Photobucket.
• Timestamp of Request (<timestamp>) - Current seconds since epoch, GMT.
• Random Nonce string (<nonce>) - Random string for this request.
• OAuth Version (<version>) - Always '1.0' for this API.
• Signature Method (<signature_method>) - Always 'HMAC-SHA1' for this API.
• URL to call (<url>) - Whole URL, up to the '?' of the querystring that you are requesting. All calls to this API have the hostname "api.photobucket.com" regardless of the hostname you are actually calling. E.g., you might request api123.photobucket.com, based on the user you are accessing, but the string provided to the OAuth "Base String" in step 2 is always "http://api.photobucket.com".
• Request Parameters (<params>) - List of request parameters to call, typically represented as an array of (key,value) pairs.

2. Generate the Base String:

• Normalize the parameters:
  • Add the OAuth specific parameters for this request to the input parameters, including:
    • oauth_consumer_key = <consumer_key>
    • oauth_timestamp = <timestamp>
    • oauth_nonce = <nonce>
    • oauth_version = <version>
    • oauth_signature_method = <signature_method>
  • Sort the parameters by name lexographically (byte ordering, the standard sorting, not natural or case insensitive). If the parameters have the same name, then sort by the value.
  • Encode the parameter values as in RFC3986 Section 2 (i.e., urlencode).
  • Create parameter string (<paramstring>). This is the same format as HTTP 'postdata' or 'querystring', that is, each parameter represented as name=value separated by &. For example, a=1&b=2&c=hello%20there&c=something%20else
• Construct the request URL (<url>). For Photobucket, this ALWAYS begins with http://api.photobucket.com. Then, add the path, ALWAYS without the trailing slash. For example, http://api.photobucket.com/search/term.
• Get the HTTP Request Method (<method>) - (GET, PUT, POST, DELETE).
• Create the Base String <base> by concatenating the elements and encoding each element, separated by '&' (urlencode via RFC3986 Section 2). The string is like encode(<method>)+&+encode(<url>)+&+encode(<paramstring>) where encode() is the urlencode function and + is concatenation. For example, GET&http%3A%2F%2Fapi.photobucket.com%2Fsearch%2Fterm&a%3D1%26b%3D2%26c%3Dhello%2520there%26c%3Dsomething%2520else

3. Generate the Signature Hash:

• Calculate the signature value via HMAC-SHA1 with the Base String <base> as the data and the Consumer Secret <consumer_secret> appended with & as the key (<signature>). This is done by hmac_sha1(<base>, <consumer_secret>+&) where hmac_sha1 is the hash function and + is concatenation. For example, hmac_sha1(GET&http%3A%2F%2Fapi.photobucket.com%2Fsearch%2Fterm&a%3D1%26b%3D2%26c%3Dhello%2520there%26c%3Dsomething%2520else, consumerkeystring&)

4. Generate the authenticated URL.

• By appending the signature to the parameters as oauth_signature, urlencoded, you can then construct the URL to send as the request. <authedurl> = <url>?<paramstring>&oauth_signature=tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D

Requesting a Page as a Logged-in User

Requests that get private content or write to a user's data (uploads, properties, etc.) must be authenticated as a user. The signing process that follows amends the process in Requesting a Page Anonymously and follows the OAuth Section 6 procedure for getting a user-based access token. See Web User Login for specific details on how to log in as a user.

• Use the Photobucket API libraries that are provided, and use the Consumer Key and Consumer Secret as necessary. Use the login procedure to receive the access token necessary.
• Use another OAuth request library. (There are a few available from OAuth.net's repository). Remember that the URL ALWAYS has the hostname "api.photobucket.com", regardless of the actual host being called, to avoid confusing during redirects that may happen. Use that library to follow the login procedure to receive the access token necessary.

Signing Process 

The procedure from the Requesting a Page Anonymously section is mostly copied here. Parts added for user authentication are noted in bold green italics.

1. Gather your parameters:

• Your Consumer Key (<consumer_key>) - Received from Photobucket.
• Your Consumer Secret (<consumer_secret>) - Received from Photobucket.
• User Token Key (<token>) - Received from access request.
• User Token Secret (<token_secret>) - Received from access request.
• Timestamp of Request (<timestamp>) - Current seconds since epoch, GMT.
• Random Nonce string (<nonce>) - Random string for this request.
• OAuth Version (<version>) - Always '1.0' for this API.
• Signature Method (<signature_method>) - Always 'HMAC-SHA1' for this API.
• URL to call (<url>) - Whole URL, up to the '?', of the querystring that you are requesting. All calls to this API have the hostname "api.photobucket.com" regardless of the hostname you are actually calling. E.g., you might request api123.photobucket.com, based on the user you are accessing.
• Request Parameters (<params>) - List of request parameters to call, typically represented as an array of (key,value) pairs.

2. Generate the Base String:

• Normalize the parameters:
  • Add the OAuth specific parameters for this request to the input parameters, including:
    • oauth_consumer_key = <consumer_key>
    • oauth_token = <token>
    • oauth_timestamp = <timestamp>
    • oauth_nonce = <nonce>
    • oauth_version = <version>
    • oauth_signature_method = <signature_method>
  • Sort the parameters by name lexographically (byte ordering, the standard sorting, not natural or case insensitive). If the parameters have the same name, then sort by the value.
  • Encode the parameter values as in RFC3986 Section 2 (i.e., urlencode).
  • Create parameter string (<paramstring>). This is the same format as HTTP 'postdata' or 'querystring', that is, each parameter represented as name=value separated by &. For example, a=1&b=2&c=hello%20there&c=something%20else
• Construct the request URL (<url>). For Photobucket, this ALWAYS begins with http://api.photobucket.com. Then, add the path, ALWAYS without the trailing slash. For example, http://api.photobucket.com/search/term.
• Get the HTTP Request Method (<method>) - (GET, PUT, POST, DELETE).
• Concatenate the elements by encoding each element (urlencode via RFC3986 Section 2), separated by '&'. This is the Base String <base>. The string is like encode(<method>)+&+encode(<url>)+&+encode(<paramstring>) where encode() is the urlencode function and + is concatenation. For example, GET&http%3A%2F%2Fapi.photobucket.com%2Fsearch%2Fterm&a%3D1%26b%3D2%26c%3Dhello%2520there%26c%3Dsomething%2520else

3. Generate the Signature Hash:

• Calculate the signature value via HMAC-SHA1 with the Base String <base> as the data and the Consumer Secret <consumer_secret> appended with &, and appended with the User Token Secret <token_secret>, as the key (<signature>). This is done by hmac_sha1(<base>, <consumer_secret>+&+<token_secret>) where hmac_sha1 is the hash function and + is concatenation. For example, hmac_sha1(GET&http%3A%2F%2Fapi.photobucket.com%2Fsearch%2Fterm&a%3D1%26b%3D2%26c%3Dhello%2520there%26c%3Dsomething%2520else, consumersecretstring&tokensecretstring)

4. Generate the authenticated URL.

• By appending the signature to the parameters as oauth_signature, urlencoded, you can then construct the URL to send as the request. <authedurl> = <url>?<paramstring>&oauth_signature=tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D

See the code examples in Logging In, and also see End User Authentication.

Open topic with navigation