Authentication of REST Requests

Authentication is the process of verifying the identity of the sender of a request. Authentication ensures that only those requests made by the person or party responsible for the GoPets account specified in the request are accepted and allowed to access private data. Authentication also allows GoPets to track the usage of GPAPI on a per-request basis.

Every non-anonymous request to GPAPI must contain authentication information to establish the identity of the requester. Any non-authenticated REST request to GPAPI will be automatically assumed to be an anonymous request (see Anonymous REST Requests).

Requesters identify themselves for authentication by specifying their GoPets ID as part of the authentication information. In addition, the request must include some sort of evidence that the requester knows the GoPets password corresponding to the specified ID, for example by using it to sign the request. Finally, for tracking purposes, the GPAPI DevToken assigned to the application developer must also be included.

Authentication information is required to establish the identity of the client making the request. In REST, this is accomplished by properly formatting the request headers, and then signing the headers using your GoPets password.

There are two ways to send your signature with a request: put your GoPets ID and the computed signature into the authorization header, or send it as a URL-encoded parameter in the query string of the request.

Authenticating via Authorization Header

When authenticating via the Authorization header, the string to be signed is formed by concatenating the request verb with the specified target resource and the request-signing headers. The headers used for request signing are: Content-Type, Date, and anything that starts with X-GP-. The string is formed by appending the verb, resource, content-type value, date value, standardized x-gp- headers (see below) separated by newlines.

x-gp- headers are standardized by formatting them as follows:

• convert the header name to lowercase
• sort by name
• remove whitespace around the : in the header
• separate headers by newlines

Important Notes

• All strings must be UTF-8 encoded
• The hash function to compute the signature is HMAC-SHA1. See RFC 2104 (http://www.ietf.org/rfc/rfc2104.txt).
• The Date in the header must be within 15 minutes of GPAPI server time. Out of bound timestamps will cause the request to be rejected.

Authentication Example 1

For example, you want to sign the following request:

GET /User/Inventory HTTP/1.0
Content-Type: text/html
Date: Sun, 25 Jun 2006 09:49:44 GMT
X-GP-DevToken: 44CF9590006BF252F707
X-GP-ID: cbscribe

The string to be signed would be:

GET\n/User/Inventory\ntext/html\nSun, 25 Jun 2006 09:49:44 GMT\nx-gp-devtoken:44CF9590006BF252F707\nx-gp-id:cbscribe

If the user's GoPets password is "foobar", the signature would be computed like so:

use Digest::HMAC_SHA1 qw(hmac_sha1 hmac_sha1_hex);
use Digest::MD5 qw(md5 md5_hex);
$passwd = 'foobar';
$key = md5_hex $passwd;

$data = "GET\n/User/Inventory\ntext/html\nSun, 25 Jun 2006 09:49:44 GMT\nx-gp-devtoken:44CF9590006BF252F707\nx-gp-id:cbscribe";

$hmac = Digest::HMAC_SHA1->new($key);
$hmac->add($data);

$sig = $hmac->b64digest . '=';

The resulting key would be "7VBlglEAtqiZ1dRiOuoD5YhVE+E=", which you would use in the Authorization header for the following result:

GET /User/Inventory HTTP/1.0
Authorization: GPAPI cbscribe:7VBlglEAtqiZ1dRiOuoD5YhVE+ECB-
Content-Type: text/html
Date: Sun, 25 Jun 2006 09:49:44 GMT
X-GP-DevToken: 44CF9590006BF252F707
X-GP-ID: cbscribe

Note: The extra "=" is appended to the digest value so it is 4-character aligned as expected by the API authentication code.

Authentication Schemes

There are currently three authentication schemes (ignoring anonymous requests): User, Partner and Dual.

User Authentication

User Authentication is used when information about a single user is being altered, and that information could have been altered by using the GoPets client program. The authorization example above is a User Authentication.

A request can be identified as needing User Authentication by noting that the X-GP-ID header exists and its value matches the Authorization header ID. The signature must be created by using the password hash of the user matching the ID.

Partner Authentication

The operations under the /Server resource category require Partner Authorization. A request can be identified as needing Partner Authentication by noting that there is no X-GP-ID header. Instead the ID in the Authorization header must be the Partner ID, and the signature must be created by using the password hash of the partner.

Dual Authentication

Independent applications that are launched from the GoPets client (like mini-games), require Dual Authentication to access the operations under the /Games resource category. Because the application is acting as a proxy for the user of the application, both the user’s and application’s credentials are required.

For Dual Authentication the X-GD-ID header exists and the value is the user’s ID, but the ID in the Authorization header is the application’s ID. The user’s password hash is added to the data to be signed immediately after the request date. The signature is created from the data using the application's password hash.

Example Data for Dual Authentication

GET\n/User\ntext/html\nSun, 25 Jun 2006 09:49:44 GMT\n2dccd1ab3e03990aea77359831c85ca2\nx-gp-devtoken:44CF9590006BF252F707\nx-gp-id:cbscribe

Back to APIDraft