Coub identifies and authorizes applications and users using the OAuth 2.0 authentication protocol.

Server libraries that implements this protocol on different platforms can be found on the OAuth community web site: http://oauth.net/2/

The authentication process includes three steps:

• Application registration — firstly, your app should obtain a unique id and a secret app token from the Coub (using the page http://coub.com/dev/applications).
• Client authorization — in this step your application (a client) asks the Coub server for a temporary access token. For doing so, the client encodes its id and secret token into client credentials and sends them to the Coub server along with a callback URL.
• Receiving an access token — the Coub server responses with a message that contains authorisation code to the callback URL. The client sends the authorisation code to the Coub server; the user approves the authorisation; and with server's response the client receives an access token that should be added to every following API requests.

The application is associated to the user, who accepts its access, and, after the app is authenticated, the app becomes able to make requests on behalf of the user.

An access token is valid for 12 months. After that period of time the authentication process should be performed again.

Registering your application

To register an app you need to follow this link, being logged in to Coub, and provide some information about your application:

http://coub.com/dev/applications

Right afterwards you will get an "app_id" — application identifier, and a "secret" — secret app token, unique for each application.

Access modes

There are several access permissions that your application could be granted with:

• logged_in — the default access mode;
• create — with the ability to create coub videos;
• recoub — with the ability to recoub coub videos;
• follow — with the ability to follow channels;
• channel_edit — with the ability to edit channels.

These modes are multiplicative which means that they can be used together: for example, to have the ability to create coubs and to edit a channel you should be granted with both of the modes.

Authorizing a client

Using an HTTP request

To authorize a client you should send an authorisation GET request on the following URL:

http://coub.com/oauth/authorize

The request should have following parameters:

• redirect_uri — the callback URL which the Coub server responses in with client credentials;
• client_id — the unique application identifier;
• response_type — should be set to code .

By default, the request will be send for logged_in access mode. To request any additional modes you need to add scope parameter to the URL. All needed additional modes should be set with the "+" sign separator:

&scope=follow+recoub

The resulted request URL would look like this one:

"http://coub.com/oauth/authorize?response_type=code&client_id=eac6f6491031535222d9553440d7048b7f6401a914aedb1303c5a4991840f92f&redirect_uri=http%3A%2F%2Fyourapp.com%2Fauth%2Fcallback&scope=follow+recoub"

Following this URL the user will be asked to log in and to authorize the application.

After granting the access the Coub server redirects the user to the callback URL adding an authorisation code to the request:

http://youapp.com/auth/callback?code=21571333-D-FNNE8jfXYnlrU5BcT5nLAXa

Having the authorization code, the client can exchange it to the access token by sending a request to the Coub server URL:

HTTP POST http://coub.com/oauth/token

The request should have following parameters:

• client_id — the unique application identifier;
• client_secret — the app's secret token;
• code — the received authorization code;
• redirect_uri — the callback URL which the Coub server responses in with client credentials;
• grant_type — should be set to authorization_code.

The resulted request URL would look like this one:

HTTP POST http://coub.com/oauth/token?grant_type=authorization_code&client_id=eac6f6491031535222d9553440d7048b7f6401a914aedb1303c5a4991840f92f&redirect_uri=http%3A%2F%2Fyourapp.com%2Fauth%2Fcallback&client_secret=9a219481ba74d9af73659e7d347fe138c910e00e0fa7ddec1d76974964b5bdd2&code=21571333-D-FNNE8jfXYnlrU5BcT5nLAXa

The Coub server responses with the access token, similar to the following one:

b912d85163c0eb25cd5db2c5ad3beb0c9aff26b679050f76f907a694574dd4a2

Once the application received the access token, it should be added to every API request as the access_token parameter of the URL:

http://coub.com/api/v2/channels/notifications_viewed?access_token=b912d85163c0eb25cd5db2c5ad3beb0c9aff26b679050f76f907a694574dd4a2

With an Oauth2 gem

You can make the authorisation process easier, using one of the OAuth client libraries, for example, the Oauth2 Ruby gem: https://github.com/intridea/oauth2:

require 'oauth2'
callback = "http://yourapp.com/auth/callback"
app_id = "eac6f6491031532222d9553440d7048b7f6401a914aedb1303c5a4991840f92f"
secret = "9a219481ba74d9bf73659e7d347fe138c910e00e0fa7ddec1d76974964b5bdd2"
client = OAuth2::Client.new(app_id, secret, site: "http://coub.com")
client.auth_code.authorize_url(redirect_uri: callback)

With an OmniAuth strategy

Coub also provides Ruby clients with the official strategy to OmniAuth library: https://github.com/coub/omniauth-coub.

Using the Coub OmniAuth strategy you can easily implement Coub authorization in your Rails app:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :coub, ENV['app_id'], ENV['secret']
end

or Sinatra app:

use OmniAuth::Builder do
  provider :coub, ENV['app_id'], ENV['secret']
end