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.
Creating an OAuth Signature
You’ll need to sign every call you make to the Vimeo API. The point of signing calls is so that we can verify that each request actually comes from your application. There are four main parts when signing a call:
The Base String
This is the HTTP method, plus the base URL, plus all of your request parameters.
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.
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:
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.
These are the OAuth parameters that must be included in your base string. You’ll also need to include any API parameters that you pass.
oauth_consumer_keyYour application’s API key
oauth_nonceA randomly-generated string that is unique to each API call. This, along with the timestamp, is used to prevent replay attacks.
oauth_signature_methodThe cryptographic method used to sign the call. Vimeo only supports HMAC-SHA1.
oauth_timestampThe 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_versionYou 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.
Creating the Base String
The base string includes three elements, separated by ampersands:
Will either be GET or POST, depending on the method used to make the call.
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 sent, including OAuth parameters and API parameters. 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.
After concatenating the three parts of the base string, you’ll have something like this (but without line breaks):
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!
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.
Making an OAuth Request
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:
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.
You’ll then create a link for the user to click on with the request token.
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.
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:
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.
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:
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.