The basics

Cooper Hewitt, Smithsonian Design Museum Collections implements the basics of section 4.2 of the OAuth2 specification and assumes the following roles and relationships:

  1. There are services. Like this one. Cooper Hewitt, Smithsonian Design Museum Collections is a service.

  2. There are users. Users have accounts on services.
  3. Services have application programming interfaces (APIs). APIs allow computer programs and robots to talk to the service in computer-speak.
  4. There are applications. Applications are other programs that use a service's APIs to do stuff.
  5. Applications have API keys. An API key is like a username for applications. It is used to identify the program trying to use a service's API and, if necessary, to control access.
  6. Applications sometimes have special access tokens that allow them to perform actions on a service on behalf of a user without having to know their username and password.
  7. Access tokens are only granted with a user's approval and can be revoked by a user at any time.
  8. Access tokens have restricted permissions sets. For example some tokens might grant an application permission to read a user's private data while others might be allowed to read and write data on behalf of a user.

Access tokens (and applications)

Generating an access token for yourself

If you're just interested in creating an access token for yourself and don't want to muck about creating applications and approval pages you can use the handy authenticate-like-magic web page.

Everything described above still happens behind the scenes but the details are hidden from you. Technically you will have created an “application” that you then approved to perform actions on behalf of yourself. Both the application and the token can be deleted at any time.

You'll need to give your access token a name and tell us what kind of permissions it has and then, like magic, you'll have a new access token that you can start using the API with.

Generating access tokens on behalf of another user

For application developers wanting to request access tokens on behalf of other users there are a few more steps to complete. Specifically:

  1. There is a webpage maintained by a service where applications can be registered. The application registration page for Cooper Hewitt, Smithsonian Design Museum Collections is https://collection.cooperhewitt.org/api/keys/register/. You must have a valid user account to register an application.
  2. There is a webpage maintained by a service where users can be prompted to approve an application. The application approval page for Cooper Hewitt, Smithsonian Design Museum Collections is https://collection.cooperhewitt.org/api/oauth2/authenticate/.
  3. There is a callback URL maintained by an application where a service can send users after they've approved an application. Once a user has approved an application the service will send the user to this URL by issuing a 302 Redirect HTTP header to the user's browser. The URL will be appended with a code parameter which is a time-sensitive special token that the application uses to request an access token.
  4. There is a URL maintained by a service where an application can request an access token for a user. This is the URL that an application sends to the time-sensitive code token to in exchange for an access token. The access token exchange page for Cooper Hewitt, Smithsonian Design Museum Collections is https://collection.cooperhewitt.org/api/oauth2/access_token/.

The “URL” defined by an application does not necessarily need to represent a “web page” but does need to conform to a known scheme for a protocol handlers. Protocol handlers are used to launch applications instead of just web pages using URLs and vary from one operating system to another so that's really a discussion outside the scope of this document.

Putting it all together

In less abstract terms here's how the OAuth2 authorization flow works:

  1. You create an application and register it with Cooper Hewitt, Smithsonian Design Museum Collections. As part of the registration process you will include a URL where users will be sent to complete the authorization process.
  2. When you want a user to agree to let your application act on their behalf you send them to the application authentication page on Cooper Hewitt, Smithsonian Design Museum Collections.
  3. Once the user approves the authorization request they are returned to the URL you defined when you registered your application. The URL will contain a unique code that can be exchanged for an access token. The code is time-sensitive and is your application's proof to Cooper Hewitt, Smithsonian Design Museum Collections that a user has approved the authorization request.
  4. Your application exchanges the code for an access token and stores the token in a safe and secure place. Your application is now ready to issue API calls on behalf of the user associated with the access token.

Examples

Pseudo-code: Getting a grant token

This is the part where an application builds a URL that you will send a user to in order to approve your application. Cooper Hewitt, Smithsonian Design Museum Collections does not allow applications to specify a callback URL (sometimes called a redirect_uri) as part of the user approval process. Applications must define a redirect URL when they create a API key.


	$args = array(
		'client_id' => 'APPLICATION API KEY',
		'scope' => 'THE PERMISSIONS YOU'D LIKE YOUR APPLICATION TO HAVE',
		'response_type' => 'code',
	);

	$query = http_build_query($args);

	$url = "https://collection.cooperhewitt.org/api/oauth2/authenticate/?" . $query;

	header("location: $url");
	exit();

Pseudo-code: Exchanging a grant token for an access token

This is the code that an application executes after a user has approved the application and service has sent them back to the application's callback URL. The application looks for a request parameter called code and the turns around and send the code back to the service asking to exchange it for an access token. What an application does after the access token is returned is outside the scope of this document.


	$code = get_str("code");

	$args = array(
		'client_id' => 'APPLICATION API KEY',
		'grant_type' => 'authorization_code',
		'response_type' => 'code',
		'code' => $code,
	);

	$query = http_build_query($args);

	$url = "https://collection.cooperhewitt.org/api/oauth2/access_token/?" . $query;
	$rsp = http_get($url);

	$data = json_decode($rsp['body'], 'as hash');
	$access_token = $data['access_token'];

	$scope = $data['scope'];
	$expires = $data['expires'];

Caveats

  1. A user may choose to define an expiry date for an access token. This information is returned with an access token as a Unix timestamp. A value of 0 means that the token has no defined expiry date. Returning expiry dates for access tokens is not part of the offical OAuth2 specification.