National Library of New Zealand
Harvested by the National Library of New Zealand on: Aug 24 2011 at 11:18:09 GMT
Search boxes and external links may not function. Having trouble viewing this page? Click here
Close Minimize Help
Wayback Machine

OAuth is complicated, so we've created this guide to help you out. We've tried to simplify it, but if you get stuck, there are a lot of other good resources out there on the internet. A great place to start is the Getting Started guide on the OAuth website. There are also lots and lots of OAuth libraries that can dramatically simplify your life, do you never have to get into the nitty-gritty. Check 'em out!

Signing an OAuth request

You'll need to sign every call you make to the Vimeo API using a system called OAuth. The point of signing calls is so that we can verify that each request actually comes from your application. There are four pieces of information you need to sign a call:

  • The Base String

    This is a string that includes the HTTP method, the base URL, the required OAuth parameters, plus all of your request parameters for the particular method you are calling.

  • The Consumer Key

    This is a public string that is unique to your application.

  • The Consumer Secret

    This is a secret that you'll pass to a cryptographic function in order to get your signature.

  • The Signature

    This is a mix of the above information, passed through a cryptographic function. It allows us to make sure that your application is actually the source of the API call.


You'll need to percent encode all of your parameters when creating your signature. These "reserved" characters must be converted into their hexadecimal values and preceded by a % character. The rest of the characters are "unreserved" and must not be encoded.

The reserved characters are:

!   *   '   (   )   ;   :   @   &   =   +   $   ,   /   ?   %   #   [   ]

These are the percent-encoded values of the above characters:

%21 %2A %27 %28 %29 %3B %3A %40 %26 %3D %2B %24 %2C %2F %3F %25 %23 %5B %5D

Unreserved characters include upper- and lower-case letters A through Z, numbers 0 through 0, and the dash, underscore, period, and tilde.

Be careful with URL encoding functions built into languages, they may not encode all of the reserved characters, or may encode unreserved characters.

Creating the Base String

The base string includes three elements, separated by ampersands:

  • HTTP Method

    Will either be GET or POST, depending on the method used to make the call.

  • URL

    This is the base URL for the API call, percent-encoded. Include the port if it is other than 80 for HTTP or 443 for HTTPS.

  • HTTP Request Parameter String

    Concatenated list of all parameters. This includes not only the API parameters for the method you are requesting but also the OAuth parameters listed below. It should be in alphabetical order and concatenated together with ampersand separators. You should percent-encode your parameters before concatenating them, and then percent-encode the entire string.

The HTTP Request Parameter String should include the following fields:

  • oauth_consumer_key

    Your application's API key

  • oauth_nonce

    A randomly-generated string that is unique to each API call. This, along with the timestamp, is used to prevent replay attacks.

  • oauth_signature_method

    The cryptographic method used to sign the call. Vimeo only supports HMAC-SHA1.

  • oauth_timestamp

    The number of seconds that have elapsed since midnight, January 1, 1970, also known as UNIX time. Make sure this timestamp is within 10 minutes of the actual time, or the request will fail.

  • oauth_version

    You don't need to include this, but if you do, it must be 1.0. It's a good idea to include it anyway, because the OAuth spec may change in the future.

Complicated, right? Let's build an example request using some bogus OAuth information. Let's say we want to call the vimeo.people.getInfo method on user 'brad'.

In this example case:

The HTTP Method is GET (not to be confused with the API method, below)
The URL is
The method is vimeo.people.getInfo
There is only one API parameter for vimeo.people.getInfo: user_id is brad
The oauth_consumer_key is abcdef0123456
The oauth_nonce is r4nd0m1234
The oauth_timestamp is 1314184689
The oauth_signature_method is HMAC
The oauth_version is 1.0

Following the steps above for building the HTTP Request Parameter String, we need to first percent-escape the values of each OAuth and API parameter. Then, sort alphabetically and concatenate the fields and parameters in HTTP query string format (in other words, using ampersands and equals signs). With the example data we would get this:


Note how user_id comes last in this list because it's sorted alphabetically. If we called a different method with parameters that started before 'o', they would appear before the oauth_* parameters.

Now we percent-escape the HTTP Request Parameter String we've built and also percent-escape the URL. Take the escaped HTTP Method, URL and HTTP Request Parameter String and concatenate them together with ampersands:


Congrats! This is the Base String.

Creating the Key

The next step is to create the key that we'll pass into the cryptographic function to generate our signature.

Most OAuth requests will include both your Consumer Secret and a Token Secret. When you have both, the key will look like this:


If you don't have a token yet, the key will look like this:


Make sure you include the ampersand at the end!

Note: The value of TokenSecret is dependent on what you're trying to do. Typically it is the token obtained from a user authenticating your application. See the Authenticating a User section below on how to get this token.

Generate the signature

Now we'll take both strings that we made, the base string and the key, and pass it into our hash function to get our signature. In PHP, it looks like this:

hash_hmac('SHA1', base_string, key, true)

The function will return a 20-character ASCII string. Because many of the characters in the string can't be sent in a URL, we need to get a base-64 encoded version of our string. In PHP we can use the base64_encode() function to do this. The final step in preparing the signature is to make sure that it is percent-encoded.

One last note on formats...

There are three ways to pass OAuth parameters to the API: through the OAuth Authorization header, POST body, or GET variables. The easiest way to pass OAuth parameters is as part of the URL, but you can use any of the three methods. See the Parameters section of the OAuth spec for more information.

Authenticating a User

Note: This process is designed for web applications, but can also be used by desktop applications.

You may hear this process called "3-Legged OAuth" elsewhere. Here's how it goes:

  1. Your application sends a request with your consumer key, and signed with your consumer secret, for a something called a request token. If we verify your application correctly, we'll send you back a request token and a token secret.
  2. You'll then create a link for the user to click on with the request token.
  3. When the user gets to Vimeo, they'll be prompted to allow your application access to their account. If they click yes, we'll send them back to your application, along with a verifier.
  4. You'll then use the request token, verifier, and token secret to make another call to us to get an access token. The access token is what you'll use to access the user's information on Vimeo.

Let's get started!

Register an application

To use the Advanced API, you'll need to register your application with Vimeo. When you register, you'll receive a Consumer Key and Consumer Secret, which you'll need to sign your API requests. You can register a new application, if you haven't done so already.

Remember, do not share your secret with anyone!

Get an Unauthorized Request Token

The first part of authorization is to get a Request Token. This token will be used to obtain an Access Token once the user authorizes your application. It's called "unauthorized" because the user hasn't given their permission yet. You'll only have to include the OAuth parameters for this call, so your base string should look like this:


If you want to use the callback specified in your application settings, set oauth_callback to "oob".

Then sign your request (this request doesn't include a token, so your signature key will be YourConsumerSecret&) and call the following URL:

Passing this as the Authorization header:

Authorization: OAuth realm="",

The result will be something like this:


Make sure to store both of these values, you'll need the secret for step 4.

Forward the user to the Authorization URL

Next, you'll need to send the user to the authorization url to log in to Vimeo and approve access for your application. You'll need to include two parameters: the oauth_token you got from the last step and the permission level. Valid permission levels are read, write, delete.

There's no need to sign this call because each request token is specifically associated with one application.

When the user signs in successfully, we'll redirect back to your application's callback URL, along with the oauth_token and an oauth_verifier.

If your application does not have a callback, the verifier will be displayed to the user and they'll be instructed to return to your application and enter the verifier.

Exchange Request Token for an Access Token

When your callback receives the authorized request token, you're ready to exchange the request token for an access token that will let you act on behalf of the user. This call needs to be signed, so your signature base should look something like this:


Then sign your request and call the following URL:

Passing this as the Authorization header:

Authorization: OAuth realm="",
oauth_verifier="YourVerifier", oauth_version="1.0",

You'll get back something like this:


You should now store both of those values as you'll need them to make calls to the API. The token and secret are valid until the user revokes access to your application, so make sure to store them in a safe place.