Authentication

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)

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	MUST be set to "code"
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.

Receive your authorization code

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.

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

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