Prerequisite: Before you start, we recommend you use an existing OAuth 2.0 library, or one of our official libraries.

Overview

So you want to authenticate your app to access a user’s Vimeo content via the Vimeo API. Cool. The Vimeo API uses OAuth 2.0 to authenticate applications, so all you need to do is:


  1. Choose your authentication workflow: Before you generate an authentication token, you need to decide which type of token you need. Find the token that fits your workflow by answering this question: Is your app accessing public or private content?
  2. Generate your token
    1. For public content: Make a direct request to the Vimeo API to create a public access token.
    2. For private content: Send your user to Vimeo to grant your application permission to act on their behalf. Then you’ll receive your authorization code, which you can exchange for an access token.
  3. Make an API request: Access tokens allow you to interact with the Vimeo API until the token expires or is revoked. Tokens are limited by the token scopes you request when creating the access token.

Note: If you want to embed your own videos on your own website (and only use Vimeo for transcoding and hosting services), you do not need to use the API to authenticate your application. All you need to do is generate a new token from your app page and include it in your application. This is a special case in which you are both the end-user and the application owner. And because you’re special, you can skip the rest of this document.

Authentication Workflow

Vimeo API applications need to provide authentication information using one of the following two OAuth 2.0 workflows:


  • Application is accessing public content (unauthenticated requests): In this workflow, the access token is not associated with a user; it is associated only with your application. The OAuth specification refers to this type of permission as a "client credentials grant". This workflow requires no authorization from the user on behalf of the application. The application merely requests an access token by sending its credentials, its client ID, and client secret, to the authorization server. The advantage of this approach is faster response time for the user without any user action. But the user can only view public content.


  • Application is accessing private content (authenticated requests): In this workflow, the access token is associated with an authenticated user who authorizes your app to act on their behalf and access their private content.The OAuth specification refers to this type of permission as an authorization code grant. The application requests an access OAuth Token (valet key) to access the Vimeo APIs (enter the house) on the user's behalf, without the user needing to enter any credentials. The user explicitly names the particular rights requested (scope) when granting the access to the app.

    This workflow is most commonly used by apps that provide additional features to Vimeo users, for example Vimeo mobile apps or user-focused video management tools. Note that if you build a service for Vimeo users to interact with their account, each user requires a distinct access token.

    Authenticated requests rely on redirection, which means that the application must be capable of interacting with the user's web browser and receiving API authorization codes that are routed through the browser. The advantages of this approach are that users enter their log-in credentials only on vimeo.com, not in your application, and neither the source code nor the Client Secret are publicly exposed. But this approach requires your users to access a web page on vimeo.com and then choose to approve/deny your application’s request.

Generate unauthenticated tokens

To get an unauthenticated access token, you should make an HTTP POST request to https://api.vimeo.com/oauth/authorize/client, along with an authorization header and some parameters.

POST https://api.vimeo.com /oauth/authorize/client
Field Required Description
grant_type Yes MUST be set to "client_credentials"
scope No Defaults to public; this is a space-separated list of scopes you want to access

You can build the authorization header with your client ID and client secret:

"Authorization : basic " + base64(client_id + ":" + client_secret)

Note: Vimeo will automatically delete tokens that have not been used for an extended period of time. If your API calls are months apart you might need to create a new token.

Generate authenticated tokens

Send your user to Vimeo

The first step of the redirect process is to send the user's client (browser) to vimeo.com. This is generally accomplished by providing the authorize URL as a link on a web page.

https://api.vimeo.com/oauth/authorize?client_id=XXXXX&response_type=code&redirect_uri=XXXX.YYY/ZZZZZ&state=XXXXXX

https://api.vimeo.com /oauth/authorize
Field Required Description
response_type Yes If you plan on storing this token for a long period of time on a server, provide "code" and follow the Authorization Grant workflow. If you plan on using this token in the browser, your token will have an automatic expiration and you should provide "token". This browser system is called the "implicit" grant
client_id Yes Your client identifier
redirect_uri Yes This field is required, and must match one of your application’s redirect URI’s
scope No Defaults to "public" and "private"; this is a space-separated list of scopes you want to access
state Yes A unique value which the client will return alongside access tokens

The user will have the option to accept or deny your app’s request to access their account, and to deny any of the scopes you requested (except for public).

Note: When the user clicks the link, they must first log in to Vimeo to authenticate their identity unless they are already logged in.

Implicit Grant Workflow

Once the user has accepted your app in the implicit grant workflow they will be immediately redirected to your redirect_uri with three values in the URL fragment (after the #)

Key Type Description
Access Token String The access token you can use to make API requests. See Making Requests for more details
token_type String This value will always be "bearer" because we only support bearer tokens in the Vimeo API
state String You must validate that this state is identical to the state you provided when sending your user to Vimeo. If the values do not line up someone may be attempting to hijack the authorization process
expires_in Integer The token you generate is short lived. expires_in will tell you how long in seconds until the token expires

Example

If your redirect_uri is https://www.example.com/implicit, your final redirect may look something like this:

https://www.example.com/implicit#access_token=2afa184ee4rb2eb69de7779932c07c5a&token_type=bearer&scope=public+private&state=h3110-w0r16&expires_in=3600

Note: Parameters added to your redirect url will be respected, but the fragment will be stripped out.

https://www.example.com/implicit?secure_key=abcdefgg#a=b will become https://www.example.com/implicit?secure_key=abcdefgg

Once you have the token from the Implicit grant you are ready to go. Refer to Making Requests for how to use the token to make API requests. If you are using the Authorization Grant, please refer to the docs on the Authorization Grant.

Authorization Grant Workflow

If the user accepts your app, they are redirected to your redirect_uri along with two query parameters:

code A string token you must exchange for your access token
state The state you provided earlier. You must validate that this matches your original state. If the state does not match, you should not attempt to exchange the authorization code.

Exchange the code for an access token

When the user returns to your site, you must exchange the code for your access token. Make an HTTP POST request to https://api.vimeo.com/oauth/access_token with your authorization header, and the following parameters.

POST https://api.vimeo.com /oauth/access_token
Field Required Description
grant_type Yes Must be set to "authorization_code"
code Yes The authorization code received from the authorization server
redirect_uri Yes Must match the redirect uri from the previous step

The authorization header can be built with your client id and client secret:

"Authorization : basic " + base64(client_id + ":" + client_secret)

Receiving the Access Token in the Authentication Response

If the authorization is valid, the API will send a final authentication response containing the access token along with some additional fields. Now the application is authorized! It may use the token to access the user's account via the Vimeo API, limited to the actions allowed by the token scope, until the token expires or is revoked.


{
    "access_token": "TOKEN",
    "token_type": "Bearer",
    "scope": "private interact create edit upload delete public",
    "user": { USER }
}
Parameter Description
access_token The token you use to make an API request
token_type The type of token (Vimeo only supports Bearer at the moment)
scope The final scopes the token was granted. This list MAY be different from the scopes you requested. This will be the actual permissions the token has been granted.
user This is the full user response for the authenticated user. If you generated your token using the client credentials grant, this value is left out.

Note: Vimeo will automatically delete tokens that have not been used for an extended period of time. If your API calls are months apart you might need to create a new token.

Best Practices

Making Requests

After you have either an authenticated or unauthenticated access token (as explained in the preceding sections), send the access token through the authorization header:

curl -H "Authorization: Bearer <OAUTH_TOKEN>" https://api.vimeo.com

If your access token only has the public scope you can use the access_token query string parameter instead of the authorization header

curl https://api.vimeo.com/?access_token=<OAUTH_TOKEN>

Supported Scopes

private View private videos
public View public videos
purchased View Vimeo On Demand purchase history
purchase Purchase Vimeo On Demand videos
create Create new videos, groups, albums, etc.
edit Edit videos, groups, albums, etc.
delete Delete videos, groups, albums, etc.
interact Interact with a video on behalf of a user, such as liking a video or adding it to your Watch Later list
upload Upload a video
promo_codes Manage Vimeo On Demand promotions
video_files Access additional video files owned by the authenticated user
Send Feedback