What is a Partner?

Partner sites are generally video sharing sites or platforms that manage hundreds of TubeMogul accounts. If you do not have a partner_id already, then you probabaly should skip this document and read our Standard Authentication document.

If you are not sure if you are a partner or a standard user or if you are interested in leveraging TubeMogul funcitonality for your users, click here to inquire.

Partner Authentication (partners only)

Partner authentication is similar identical to Standard Authentication, except that you will be authenticating on behalf of another user. Therefore, you will use a combination of secret_key, partner_id and user_token to identify both your application and the person who is using it.

Your secret_key and partner_id are assigned to you when you partner with TubeMogul. And the user_token is acquired when a user links their TubeMogul account with your application.

To find out how to link users to your application, read Obtaining User Tokens.

Obtaining User Tokens

NOTE: This document applies to partner calls only. You do not need a user_token parameter for queries to your own account. See Standard Authentication.

In order to make an API call on behalf of another user, an application must obtain a user token. User tokens are persistent and unique identifiers of a user's account. They are only available to applications that have been approved by the user. Applications should obtain and store these tokens in order to make subsequent API calls.

To obtain a user's token you would link the user to this form:
http://www.tubemogul.com/auth/login2?pid=<partnerID>
(Alternatively, you can direct users to this page if you are
certain that they are not already TubeMogul users
http://www.tubemogul.com/signup/index2?pid=<partnerID>)

This page will guide the user through the account registration process and create a user token for them.

The process will end on the myaccount/partner page which will display the user's token. You may either

Instruct the user to copy/paste the token into your application
OR
Follow the steps listed in the Advanced Topics section, below, to automatically grab the token.

Credential Entry

After the token generation process, users need to enter their account credentials for each of the video sharing sites where they want to launch videos.

Once the user has saved their credentials, all required user information has been stored on the TubeMogul site and the partner website can invoke the various TubeMogul API methods to upload videos on behalf of the user.

Advanced Topics

Styling the registration and credentials pages

Partners can apply a custom css stylesheet to the framed pages by passing a "css" request parameter that contains the URL to a CSS stylesheet on the partner site. TubeMogul will apply your style sheet to the registration and/or credentials pages. The CSS stylesheet can extensively skin the TubeMogul pages to match the look and feel of the partner site.

Obtaining the user token automatically

To obtain the user token without requiring the user to copy/paste it into your app, TubeMogul offers a callback url option. A callback URL is a URL that we will call after registration or login which includes the user token. Since this URL is hosted on your server you can capture the token and store it for future use.

To enable the callback, simply pass the callback URL (including any parameters you may require such as a user ID) as a GET parameter to the registration or login pages. For example:
http://www.tubemogul.com/auth/login2?pid=partner_id&callback_url=http%3A%2F%2Fwww.mysite.com%2Fcallback.php

After the user logs in they will be redirected to your callback page with two additional GET parameters:

user_token - This will contain the user token that was obtained for the user. You should record this value in your system associated with the user.
redirect_url - After recording the userToken, redirect the browser to the URL specified here (such as with a HTTP 302 response). This will keep the workflow seamless for the user.

For example, if you passed the callbackUrl shown above, your servers would receive a GET request such as the following after the user completes the login/registration process:
http://www.mysite.com/callback.php?user_token=xyzxyzxyzxyz&redirect_url=http%3a%2f%2fwww.tubemogul.com%2fmyaccount%2fpartner%2f%3fpid%3dpartner_id

You should record the user_token "xyzxyzxyzxyz" and redirect to:
http://www.tubemogul.com/myaccount/partner/?pid=partner_id

How to Create the querystring and auth token

Important Note: All parameters sent in application/x-www-form-urlencoded requests must be URL encoded according to RFC 1738.

List of variables:

Complete string to be hashed:

Prepend the secretKey to the entire request query string:

78d393df54275b42152127b672ed865a6f2d1ef0user_token=bc54a4fa3520f3f36f08a54a4efe043b
&method=get_video_status&partner_id=6bb13cb12d3f3926e927679b1b7c43547dd6af10
&date=1189384112&upload_id=3098

auth: 62c5bbc4e618b7491bc654d48fedd2a5937f7185
(SHA-1 hash of the string above)

Actual request body:

user_token=bc54a4fa3520f3f36f08a54a4efe043b&method=get_video_status
&partner_id=6bb13cb12d3f3926e927679b1b7c43547dd6af10&date=1189384112
&upload_id=3098&auth=62c5bbc4e618b7491bc654d48fedd2a5937f7185

Sample multipart/form-data Request

Note: Parameters sent in multipart/form-data requests should *NOT* be URL encoded.

List of Variables:

secret_key: 78d393df54275b42152127b672ed865a6f2d1ef0
(provided by TubeMogul, this is NEVER transmitted over the Internet)

partner_id: 6bb13cb12d3f3926e927679b1b7c43547dd6af10
(provided by TubeMogul)

method: upload_video
(uploads a video to a user's TubeMogul account)

user_token: bc54a4fa3520f3f36f08a54a4efe043b
(generated by each website user; a required parameter for most methods)

date: 1189384519
(UNIX timestamp that must be generated each time a request is being built)

title: my pets
(a required parameter for upload_video method)

tags: dog, cat, farm
(a required parameter for upload_video method)

description: my dog attacks my cat
(a required parameter for upload_video method)

category: 13
(a required parameter for upload_video method)

token: 1342342083
(obtained from call to which_host method; a required parameter for upload_video method)

file: [BINARY DATA FOR FILE: pets.mpeg]
(the filename is not sent separately since it is received in the file information)

Complete string to be hashed:

Concatenate the secret_key, the user_token, the method name being called, the partner_id, the date, the video title, and the video filename.

78d393df54275b42152127b672ed865a6f2d1ef0bc54a4fa3520f3f36f08a54a4efe043bupload_video
6bb13cb12d3f3926e927679b1b7c43547dd6af101189384519my petspets.mpeg

auth: 779a0ea80841e7f3ec4a525449bd9150667680a2
(SHA-1 hash of the string above)

Actual request body:

------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="user_token"

bc54a4fa3520f3f36f08a54a4efe043b
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="method"

upload_video
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="partner_id"

6bb13cb12d3f3926e927679b1b7c43547dd6af10
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="date"

1189384519
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="title"

my pets
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="token"

1342342083
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="tags"

dog, cat, farm
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="description"

my dog attacks my cat
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="category"

13
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="file"; filename="pets.mpeg"
Content-Type: application/octet-stream

[BINARY DATA FOR FILE]
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3
Content-Disposition: form-data; name="auth"

779a0ea80841e7f3ec4a525449bd9150667680a2
------------ei4cH2ae0cH2ei4Ef1Ef1GI3KM7GI3--