OAuth and the TwentyThree API
OAuth is a secure, open protocol, which specifies a standard way to access protected data on different websites. Roughly, the protocol outlines 1) a method for letting users grant an application access to a web service API, and 2) how to communicate using these credentials.
The TwentyThree API uses OAuth to authorize access for a few different reasons:
- It's well-documented.
- It's open and secure.
- It's used by Google, Yahoo, Twitter and multiple other web services. This means that developers may be able to re-use code, and that it's almost certain that they'll be able to re-use one of the stable OAuth libraries available for most popular programming languages.
The purpose of the document is not to introduce OAuth; for this there are great beginner's guides. Instead this document outlines how the API works with OAuth; illustrates the authorization flow; and it lists some sample scripts to help you get started.
Signing and making requests
This section details the specifics of the OAuth implementation in the TwentyThree API. For newcomers to OAuth, the following sections introduces some tricky parts of the protocol and gives an example of the authorization and communication flow.
The TwentyThree API only supports the 1.0a version of the OAuth protocol, and
oauth_callback is required when asking for a request token.
We only support the the HMAC-SHA1 signature method.
OAuth parameters and signatures may be included either in an HTTP
Authorization header, in the post body of a POST request, or in the query string of a GET request. Please note, that you won't be able to include any parameters in the URL query string during POST requests.
To get help testing your request signatures, check out this wonderful tool.
When talking to the TwentyThree API you'll be using these URLs:
|Request Token URL:||http://api.visualplatform.net/oauth/request_token|
|Access Token URL||http://api.visualplatform.net/oauth/access_token|
It's clear from these URLs that you'll be changing domain context half-way through the process. This switch is handled by reading the response body from
oauth_token=12-N9KNOy8ec3BWqCtR75HZ &oauth_token_secret=yndh3sxnlasykxpsmposzrjeyUptdumfwax0rjdobqimkytvsdkacztlFqzvyfgh &domain=videos.example.com &user_id=12345
Armed with this response, you'll know which domain (
domain) to query and which user (
user_id) has authorized your access.
During the authorization stage, you can control your user's log-in flows by setting a callback when calling
request_token. For example, set
oauth_callback=http://mysite.com/callback to control how the user is redirected back to your application after authorizing your request token. When
oauth_callback is omitted or set to
oob (out of band), the end user is given a
oauth_verifier which your application must manually ask for in order to exchange your request token for an access token. The callback process is outlined in the OAuth docs.
In accordance with the OAuth request normalization specification the following parts of the request must be included in the signature:
- All parameters in the OAuth HTTP Authorization header except
- All parameters from the URLs in the query part of an HTTP GET.
- All parameters from the request body of a
application/x-www-form-urlencodedHTTP POST request.
This probably seems like an excessively boring thing to iterate here, but it's important to note that the parameters of a
multipart/form-data HTTP POST request are not included in the signature. This means, for example, that the content of a photo or video file uploaded via the API won't be included in the signature.
Access token timeouts
When issued, access tokens and their secrets do not time out on their own. However, users are always able to revoke their authorization, so your application (or consumer) should be able to handle this case smoothly.
Understanding OAuth keys and tokens
There are three key/secret pairs to be aware of in OAuth:
- A consumer key is used to identify the application, while its associated consumer secret is used to sign all requests and thus verify the identity of the application.
- A request token is retrieved by the application alone, and is used to ensure that an end user authorizes your application to submit API operations on the user's behalf. Its associated request token secret is used to sign requests during the authorization process.
- An access token is retrieved after the end user has authorized your application. Its associated access token secret is used to sign all requests on behalf of the user and thus verify the identity of both the application and the user.
The end-goal of the authorization process where the user grants application access is an access token and secret. Once this process is completed, only the consumer key/token and the access key/token is needed to make and assign requests.
Make absolutely sure that you never share either secret with an untrusted party. The OAuth protocol is set up to allow interactions without ever exchanging secrets or passwords, and the security of the communication hinges on secrets actually being secret.
Setting up your application
- Go to your site and log in.
- Go to Your profile and click the Manage applications link.
- Hit the Create your own application button.
- Now, fill in and submit the form to get your consumer key and consumer secret. When you set up your application, you'll be able to select a permission levels for the app. The level cannot be changed at a later stage.
Your new consumer key is only valid on your own site domain. If you need a generic consumer key/token, which can be used across sites, contact TwentyThree.
Applications set up in this manner can only gain read, write, or admin access. To gain super-level access to a site, a special consumer key must be set up by the site's owner.
These privileged credentials are set up under Settings → API and Applications.
The set of credentials includes both consumer key/secret and an access token/access token secret. Thus, when you're using privileged credentials to access the API, you won't need to go through the user authentication process. Even if this seems like a nice shortcut in many cases, we encourage that you only use privileged credentials when it is absolutely required by your application.
Using OAuth step-by-step
This section takes you through the process of retrieving access credentials and then using those credentials.
In this sample, we have a consumer with:
consumer_key = 571156-cuQla8tP5tzjf70znIwS consumer_secret = u5pHMUpV8wB7LxwieAnrexE8CkzoZTVs6G626KKqfPVqFp0TxT
Step 1: Get a request token
Using your consumer credentials, retrieve a request token from the provider:
GET http://api.visualplatform.net/oauth/request_token Authorization: OAuth realm="http://api.visualplatform.net/", oauth_callback="http%3A%2F%2Fmy.example.com%2Fcallback", oauth_consumer_key="571156-cuQla8tP5tzjf70znIwS", oauth_nonce="48e12d7291d99b0416f3bb30a9d2ea72", oauth_signature="ozL65XeaXv4LHnJ6y3Q8H%2F5tERI%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1267547746", oauth_version="1.0"
Signature base string:
GET&http%3A%2F%2Fapi.visualplatform.net%2Foauth%2Frequest_token&oauth_callback%3Dhttp%253A%252 F%252Fmy.example.com%252Fcallback%26oauth_consumer_key%3D571156-cuQla8tP5tzjf70znIwS%26oauth_n once%3Deb6cf9e826b6a99e6c4998bb9605f994%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp %3D1267547723%26oauth_version%3D1.0
The response to this request gets you both a request token and a related secret:
oauth_token=12-8vr9EplGHHR8Ciem8SLu &oauth_token_secret=qQptayCQG1ZQYbS73FE6WdNz4wKjYJqcvLzI9DjGD1UKP9wruL &oauth_callback_confirmed=true
Step 2: Have user authorize the token
request_token from step 1, redirect your user to the following URL to authorize your request token:
This will direct the user through the steps of authorizing your application's access. When the process is over, the user is redirected back to the URL specified in
oauth_callback from step 1:
Step 3: Exchange the request token for an access token (and get domain)
From the callback URL, you'll be able to exchange the now-authorized
request_token for an
access_token. Here, we're also using the
oauth_verifier from step 3:
GET http://api.visualplatform.net/oauth/access_token Authorization: OAuth realm="http://api.visualplatform.net/", oauth_consumer_key="571156-cuQla8tP5tzjf70znIwS", oauth_nonce="936dff7fa3d5674b1eb5c217ce6701b3", oauth_signature="vFb0a6CGy6rtXeuEfZlhOHvjhjk%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1267547767", oauth_token="12-8vr9EplGHHR8Ciem8SLu", oauth_verifier="z3pjUoZU6KN8B5n4V2Fy", oauth_version="1.0"
Signature base string:
GET&http%3A%2F%2Fapi.visualplatform.net%2Foauth%2Faccess_token&oauth_consumer_key%3D571156-cuQ la8tP5tzjf70znIwS%26oauth_nonce%3D936dff7fa3d5674b1eb5c217ce6701b3%26oauth_signature_method%3D HMAC-SHA1%26oauth_timestamp%3D1267547767%26oauth_token%3D12-8vr9EplGHHR8Ciem8SLu%26oauth_verif ier%3Dz3pjUoZU6KN8B5n4V2Fy%26oauth_version%3D1.0
The response includes your new access token and the related secret -- but you'll also get user information and, more importantly, the
domain for the data you'll be accessing:
oauth_token=3-gnS3NKP74AzcJsvbFi3Z &oauth_token_secret=83x7n5rR2eT1IV0zLNptvxxy1R3WFptGozka38tDtLZmSDYboW &domain=v.23video.com &user_id=455432
Step 4: Talk to the TwentyThree API
To talk to the API, you'll need to store
domain from step 3. Along with your consumer credentials, these are used to query the API.
For example, to get a list of photos:
POST http://v.23video.com/api/photo/list Authorization: OAuth realm="http://v.23video.com/", oauth_consumer_key="571156-cuQla8tP5tzjf70znIwS", oauth_nonce="a666b90c2339a866c8ed405e3e2821c3", oauth_signature="R6etDqoM8JLzuXK%2B3BiVeXCEqRQ%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1267547771", oauth_token="3-gnS3NKP74AzcJsvbFi3Z", oauth_version="1.0" Content-Type: application/x-www-form-urlencoded Content-Length: 10 format=xml
Signature base string:
POST&http%3A%2F%2Fv.23video.com%2Fapi%2Fphoto%2Flist&format%3Dxml%26oauth_consumer_key%3D57115 6-cuQla8tP5tzjf70znIwS%26oauth_nonce%3Da666b90c2339a866c8ed405e3e2821c3%26oauth_signature_meth od%3DHMAC-SHA1%26oauth_timestamp%3D1267547771%26oauth_token%3D3-gnS3NKP74AzcJsvbFi3Z%26oauth_v ersion%3D1.0
... and you'll get something like this in response.
<response status="ok" permission_level="admin" p="1" size="20" total_count="49" cached="0"> <photo photo_id="1234" ...> (...) </photo> (...) </response>
We've created a set of samples on how to authenticate your application and communicate with the TwentyThree API: