API v3 has been deprecated. Please use API v4 instead

Authentication

The entire Viki API V3 must be accessed using OAuth 2.0 (currently draft v22). Viki uses OAuth authentication to track API usage of your applications.

Authentication can be done in three simple steps:

1) Sign Up

NOTE API v3 has been deprecated. New applications can’t be created.

Register your application at the Viki application dashboard. You may use your normal Viki account or create a separate account to manage your applications. You will be granted a Client ID and a Client Secret.

2) Obtain Access Token

The next step in the authentication step is to get an access token. An access token is passed as a parameter with every request you make to the Viki API. You will be able to use your Client ID and a Client Secret to acquire an access token. This is done by making a POST request to http://viki.com/oauth/token with the following parameters:

  • grant_type = GRANT_TYPE
  • client_id = CLIENT_ID
  • client_secret = CLIENT_SECRET

Valid grant types are: - client_credentials: to get basic access to the API resources - password: to authenticate a user and access private resources or be able to create resources in his/her name. The request will always return the user ID on Viki system. Additional parameters are required: * username and password: If login with Viki user data * fb_access_token: If login using Facebook access token.

If the grant type is password and you decide to use the fb_access_token the user will be created in the system if the facebook_id and email are not used. In case there is a user with that particular email, it will login as him AND associate the Facebook user ID to that account.

Access tokens are valid for 24 hours. Here’s an example:

curl http://viki.com/oauth/token -d "grant_type=GRANT_TYPE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"

(Sidenote: the grant type is 'client_credentials'{.params} because no user data is currently exposed through the Viki V3 API. Therefore, we are granting your application — a ‘client’ — with credentials to access API resources.)

Here’s another example, in Ruby, using the OAuth2 gem (v0.6.1):

client = OAuth2::Client.new('CLIENT_ID', 'CLIENT_SECRET', :site => 'http://viki.com')access_token = client.client_credentials.get_token.token

3) Make a Request

Once you have an access token you will be able to use any of the Viki API’s endpoints. You may do so by adding access_token=ACCESS_TOKEN{.params} to your GET requests. For example, from the command line, you can do:

curl https://viki.com/v3/movies.json?access_token=ACCESS_TOKEN{.codeblock}

Which will return to you a list of movie objects available on Viki.

Handling Access Token Expiry

For security reasons, Viki V3 access tokens expire after 24 hours. There are two ways you can handle this expiry:

  1. Check the expiration date of the token at the start of every session and refresh it if it has expired
  2. Refresh only when the API request fails due to token expiration.

In the second scenario, the Viki API will return a 403 Not Authorized status code. You may use this as a signal to request for a new access token, after which you may reapply the failed request.