Getting started

Overview

Ustream allows third-party clients to access Ustream users' resources (data) via a HTTP-based (RESTful) API. It also provides a Broadcaster Library that is capable of broadcasting to a user's channel. Both the REST API and the Broadcaster Library uses the OAuth 2.0 protocol for authentication and authorization.

Basic workflow

The basic workflow of a third-party Client is the following:

  1. Authorize the user: Obtain and validate the user's credentials (username and password). The client must never store these credentials, only pass it to the server for authorization.
  2. Obtain an access token: If the user's credentials were entered correctly, the third-party client can obtain an access token. Once this token is received, it can be used to access the user's resources until the token expires or the user revokes it on the Ustream website.
  3. Access the user's resources: The client can use Ustream's REST API or the Ustream Broadcasting Library to access the user's resources (data) or to broadcast to the user's channel. The client authorizes itself using the access token, with methods described by the OAuth 2.0 Protocol Draft.

Authorization Flows

The OAuth 2.0 protocol provides several flows (workflows) for the first two phases. It depends on the type and architecture of the client which flow is the most suitable. The following flows are supported:

  • Implicit flow: Suitable for standalone, native clients (desktop / mobile). The user enters its credentials to a secure login webpage. After logging in, the browser is redirected to a special URL (defined by the client), passing the access token in the URL.
  • Authorization code flow: Suitable for third-party websites which contain a client and a server component. The user enters its credentials to a secure login webpage. After logging in, the browser is redirected to a special URL (defined by the client), passing an authorization code in the URL. The third-party server obtains the access token with another HTTP request in the background, using the authorization code. This method is more secure than the implicit flow if the third-party client has a client+server model. See the OAuth2 Draft for details.
  • Client credentials flow: Best choice for users developing server-side applications to manage their content / settings. Read more

Endpoints

The webpages and HTTP services invoked in during this authorization process are called endpoints. Ustream has the following endpoints:

  • Authorization endpoint: this is the webpage where the user enters his/her credentials.
  • Token endpoint: this is the HTTP service where the access token can be obtained in an authorization code flow (when using the implicit flow, the access token can be obtained directly from the authorization endpoint).

Access tokens

There are two types of access tokens: Bearer tokens and MAC tokens. They are equivalent in the sense that they can access the same resources on the Ustream REST API. The difference is that while bearer tokens can be only used on encrypted channels (HTTPS), MAC tokens are suitable on non-encrypted channels as well.

If the client uses the Ustream Broadcasting Library, it must use MAC tokens: the broadcasting is done on the RTMP protocol, which is unencrypted. If the client only uses the REST API, the bearer tokens are preferred because their usage is very simple and lightweight.

Bearer tokens and MAC tokens can be obtained in the same way: the authorization endpoint has a token type parameter, so the client can specify what kind of token it wants to create.

Token scopes, expiration

By default, access tokens have a limited lifetime (they expire in a day) and can access only a limited amount of resources. In the authorization process the client can request extra permissions (scopes) from the user to overcome these limitations. These requests are shown to the user on the authorization endpoint. Ustream currently supports the following scopes:

  • Offline scope: If this scope is enabled, the access token never expires.
  • Broadcaster scope: If this Scope is enabled, the access token can be used for broadcasting with the Ustream Broadcasting Library. This scope are enabled only for MAC tokens.

OAuth2 authorization server endpoints

Authorization endpoint

Location https://www.ustream.tv/oauth2/authorize
Supported flows Authorization code, Implicit
Supported HTTP methods GET, POST

The Authorization endpoint is a secure web page that contains a login form. The client should show this page to the user in an embedded browser. When the user completes the login process, the browser is redirected to a special URL. The client can capture this redirect call, and obtain the authorization code or access token (depending on the flow type).

The parameters below specify the behavior of the authorization endpoint. They have to be set in GET or POST HTTP parameters.

Supported OAuth 2.0 standard parameters
parameter type importance description
response_type string REQUIRED "code" for Authorization Code Flow; "token" for Implicit Flow
client_id string REQUIRED 40 character sha1 hash that identifies the Client. Provided by Ustream.
redirect_uri string REQUIRED The URI where the browser will redirect after the authentication process. The prefix of this URI must be registered at Ustream.
state string OPTIONAL This value is sent as a GET parameter to the redirect_uri, to prevent XSRF attacks. See OAuth2 Draft for details.
scope string OPTIONAL "offline" for Offline Scope, "broadcaster" for Broadcaster Scope, or space separated urlencoded list of these strings
Ustream specific extra parameters
parameter type importance description
token_type string OPTIONAL The Access Token type. If this parameter is set, must be "bearer" for Bearer Token, or "mac" for MAC token. Default value: "bearer".
device_name string OPTIONAL Full product name of the Client device or application. It is used for easy identification of the OAuth2 Token. The User will be able to review which Clients are connected to his/her account, and revoke these grants on the Ustream website.
display string OPTIONAL If set to "touch", a mobile-optimized version will be shown
lang string OPTIONAL Show the authorization page in this locale (e.g. en_US); This parameter will also set the language of the newly registered users. See section 4.2.1. for available locales.
Result

The result values below are appended to the redirect_uri as HTTP GET parameters. If the response_type parameter is "code", the following values are returned:

name description
code an authorization code (40 character length, hexa encoded sha1 hash)
state if state was sent to the endpoint, we send it back

MAC tokens are currently not implemented for Authorization Code Flow.

If the response_type is "token" and token_type is "bearer" (or not set), the following values are returned:

name description
access_token Access Token (40 character length, hexa encoded sha1 hash)
expires_in Token's current lifetime, in seconds
token_type Will be "bearer"
state if state was sent to the endpoint, we send it back

If the response_type is "token" and token_type is "mac", the following values are returned:

name description
access_token Access Token (40 character length, hexa encoded sha1 hash). Referred as macId in the Ustream Broadcaster Library.
expires_in Token's current lifetime, in seconds. Not set if Offline Scope is enabled.
mac_key MAC secret (40 character length, hexa encoded sha1 hash). Referred as macSecret in the Ustream Broadcaster Library.
created_at UTC timestamp of the creation datetime. Referred as macIssueTime in the Ustream Broadcaster Library.
mac_algorithm Will be "hmac-sha-1"
token_type Will be "mac"
state If state was sent to the endpoint, we send it back
Error handling

If the authentication was not successful, there is no HTTP redirection: the User can stay on the Authorization Endpoint page until the correct credentials are entered. It is also possible to sign up a new user, or to request a password reset if the password is forgotten.
If the User authenticates correctly, but presses "Deny" on the authorization page, the browser is redirected to the redirect_uri with the following parameters:

name description
error "access_denied"
state If state was sent to the endpoint, we send it back

Token Endpoint

Location https://www.ustream.tv/oauth2/token
Supported HTTP methods POST

Authorization Code flow

When the Client receives the Authorization Code, the server-side component of the Client calls this Endpoint to return the Access Token. The parameters below must be set as HTTP POST parameters.

parameter type importance description
grant_type string REQUIRED MUST be "authorization_code" in this case.
client_id string REQUIRED 40 character sha1 hash, provided by Ustream.
code string REQUIRED The Authorization Code received from the Authorization Endpoint.
redirect_uri string REQUIRED The redirection URI used by the authorization Server to return the authorization response in the previous step.

The Token Endpoint currently works for Bearer Tokens only.

In addition to the parameters above, the Client has to provide its Client secret (provided along with the Client key) to authenticate itself. The authentication is done with HTTP Basic authorization method. Example HTTP Header:

Authorization: Basic bc345abc45d6789abcdef0123aef0126789def01
Response

The response of the Token Endpoint is a JSON object. JSON response on success (for Bearer Tokens):

name description
access_token Access Token (40 character length, hexa encoded sha1 hash)
expires_in Token's current lifetime, in seconds. Will not be set if Offline Scope is enabled.
token_type Will be "bearer"

Resource Owner Password Credentials flow

The server-side component of the Client calls this Endpoint to return the Access Token using resource owner's credentials (username and password). The parameters below must be set as HTTP POST parameters.

parameter type importance description
grant_type string REQUIRED MUST be "password" in this case.
client_id string REQUIRED 40 character sha1 hash, provided by Ustream.
client_secret string REQUIRED 40 character sha1 hash, provided by Ustream.
username string REQUIRED Ustream username
password string REQUIRED Ustream password
device_name string OPTIONAL device name
token_type string OPTIONAL Must be "bearer" or "mac"
scope string OPTIONAL "offline" for Offline Scope, "broadcaster" for Broadcaster Scope, or space separated urlencoded list of these strings

In addition to the parameters above, the Client has to provide its Client secret (provided along with the Client key) to authenticate itself. The authentication is done with HTTP Basic authorization method. Example HTTP Header:

Authorization: Basic bc345abc45d6789abcdef0123aef0126789def01
Response
name description
access_token Access Token (40 character length, hexa encoded sha1 hash)
expires_in Token's current lifetime, in seconds. Will not be set if Offline Scope is enabled.
token_type Will be "bearer" or "mac"
mac_key MAC secret (40 character length, hexa encoded sha1 hash). Referred as macSecret in the Ustream Broadcaster Library.
created_at UTC timestamp of the creation datetime. Referred as macIssueTime in the Ustream Broadcaster Library.
mac_algorithm Will be "hmac-sha-1"

Client credentials flow

There are several API resources which aren't connected to any user. Those are resources implemented for the API client (application). Hook management is a good example for that. Those resources needs the clients to identify themselves. For that purpose we implemented the Client Credentials OAuth2 Flow which provides your app a client access token. With normal user level tokens these resources dedicated to clients are inaccessible, however a client token can access the application owner user's resources.
The parameters below must be set as HTTP POST parameters.

parameter type importance description
grant_type string REQUIRED MUST be "client_credentials" in this case.
client_id string REQUIRED 40 character sha1 hash, provided by Ustream.
device_name string OPTIONAL device name
token_type string OPTIONAL Must be "bearer" or "mac"
scope string OPTIONAL "offline" for Offline Scope, "broadcaster" for Broadcaster Scope, or space separated urlencoded list of these strings

In addition to the parameters above, the Client has to provide its Client secret (provided along with the Client key) to authenticate itself. The authentication is done with HTTP Basic authorization method. Example HTTP Header:

Authorization: Basic bc345abc45d6789abcdef0123aef0126789def01
Response
name description
access_token Access Token (40 character length, hexa encoded sha1 hash)
expires_in Token's current lifetime, in seconds. Will not be set if Offline Scope is enabled.
token_type Will be "bearer" or "mac"
mac_key MAC tokens only: MAC secret (40 character length, hexa encoded sha1 hash). Referred as macSecret in the Ustream Broadcaster Library.
created_at UTC timestamp of the creation datetime. Referred as macIssueTime in the Ustream Broadcaster Library.
mac_algorithm MAC tokens only: Will be "hmac-sha-1"
Error responses for Authorization Code, Password, and Client Credentials token flows

If there is an error, the Token Endpoint returns a JSON object with the following format:

{
    "error": "ERROR_VALUE"
}

It also sends a HTTP status code indicating the error. Possible error responses:

error value HTTP response code Error conditions
invalid_request 400 Bad Request When one or more required parameters are missing
unsupported_grant_type 501 Not implemented When Client asks for an unsupported grant type, currently only "authorization_code", "client_credentials" and "password" are supported.
invalid_grant 400 Bad Request When the supplied authorization_code does not exists or expired
invalid_client 400 Bad Request When the referred Client is missing, the secret is wrong or the authorization requester Client and token requester Client does not match.
server_error 503 Server Error The Server cannot handle the request at this moment for some reason. Try again later.

Examples

Authorization Code Flow

  1. The Client opens a browser with the Authorization Endpoint:

    https://www.ustream.tv/oauth2/authorize
    ?response_type=code
    &client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD
    &redirect_uri=http://example.com/get_access_token
    &device_name=My%20Device
    &scope=offline+broadcaster
    &display=touch
    &state=XYZ
  2. The User enters his/her credentials and presses the Allow button. The browser is redirected to the following URL:

    http://example.com/get_access_token?code=19d8dbb3ebac55f110c3b526e38bcfdfbf46d659&state=XYZ
  3. The page handler at http://example.com/get_access_token retrieves the Access Token using the Token Endpoint:

    POST /oauth2/token HTTP/1.1
        Host: www.ustream.tv
        Authorization: Basic xxxxxxxxxxyyyyyyyyyywwwwwwwwwwzzzzzzzzzz
        Content-Type: application/x-www-form-urlencoded
        grant_type=authorization_code&client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD
        &code=19d8dbb3ebac55f110c3b526e38bcfdfbf46d659&redirect_uri=http://example.com/get_access_token
        
  4. The response of Token Endpoint contains the Access Token:

    HTTP/1.1 200 OK
        Cache-Control: no-store
        Content-Type:application/json; charset=UTF-8
        {"access_token":"ab345cdef123ef1267890abcdef04567890abcd1", "token_type":"bearer", "expires_in":86400}
        

Implicit Flow, requesting for MAC tokens on a mobile-optimized authorization page

  1. The Client opens a browser with the Authorization Endpoint:

    https://www.ustream.tv/oauth2/authorize
    ?response_type=token
    &token_type=mac
    &client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD
    &redirect_uri=http://example.com/token
    &device_name=My%20Device
    &scope=offline+broadcaster
    &display=touch
    &state=XYZ
    
    1. The User enters his/her credentials and presses the Allow button. The browser is redirected to the following URL:

      http://example.com/token
      ?access_token=1a446888dfaa921e189479409d638d680dfdbf77
      &token_type=mac
      &mac_key=dfc337d39b0941650b67051a622885cb0eb67a51
      &mac_algorithm=hmac-sha-1
      &created_at=1310000546
      &state=XYZ
      
    2. The user cancels the authorization page or presses Deny after authentication. The browser is redirected to the following URL:

      http://example.com/token?error=access_denied&state=XYZ

Testing API from command line (with curl)

Get an access token

https://www.ustream.tv/oauth2/authorize
?response_type=token
&client_id=057ce944b015ec9fdf546dfbbe1b7af4b19e8158
&redirect_uri=https://www.ustream.tv/oauth2/redirect
&device_name=MyDevice
&display=touch
&state=XYZ

After logging in, the browser is redirected to a special URL (defined by the Client), passing the Access Token in the URL. As you can see in the examples below, you should use Authorization HTTP header with token in the requests: "Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950"

Creating a channel (POST)

$curl -i -X POST -H "Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950" -d "title=Whatever+Test+1234" https://api.ustream.tv/users/self/channels.json
HTTP/1.1 201 CREATED
Server: nginx/1.2.6
Date: Tue, 15 Jan 2013 13:08:06 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 123
Connection: keep-alive
Vary: Host
X-Powered-By: PHP/5.3.20-1~dotdeb.0
Cache-Control: no-store
Accept-Ranges: bytes
X-Varnish: 703443498
Age: 0
Via: 1.1 varnish
{"channel":{"id":"13091307","title":"Whatever Test 1234","url":"whatever-test-1234","tiny_url":"http://ustre.am/SVE7"}}

Acquiring the streamkey for an external broadcasting application

If you wish to use an non-Ustream provided broadcaster application or appliance (like Flash Live Media Encoder, Wirecast, Tricaster, etc., you will need a streamkey to authenticate with Ustream and proving that broadcasting to that particular channel is allowed. Also you should get the ingest point where your device or application should connect.

You can access the streamkey (it is usually the parameter "stream" in the configuration of these devices) the following way. The endpoint requires you to provide the OAuth2 authorization key to complete. The endpoint is at https://api.ustream.tv/channels/CHANNEL_ID/authorizations/broadcasting.json

Example call
GET /channels/123456/authorizations/broadcasting.json
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded
Example response
HTTP/1.1 200 OK
Cache-Control: no-store
{"streaming_key": "kqDlIyGb0H47g8SRSyKjyxAqPmiwTbw3"}

Acquiring the channelkey for an external broadcasting application

If you wish to use Flash media live encoder , you will need the channelkey to authenticate with Ustream and proving that broadcasting to that particular channel is allowed. Also you should get the ingest point where your device or application should connect.

You can access the channelkey (it is usually the parameter "stream" in the configuration of these devices) the following way. The endpoint requires you to provide the OAuth2 authorization key to complete. The endpoint is at https://api.ustream.tv/channels/CHANNEL_ID/authorizations/broadcasting/channel_key.json

Example call
GET /channels/123456/authorizations/broadcasting/channel_key.json
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded
Example response
HTTP/1.1 200 OK
Cache-Control: no-store
{"channel_key": "kqDlIyGb0H47g8SRSyKjyxAqPmiwTbw3"}