Authentication

Use of the API requires authentication. We support two methods for authenticating: OAuth 2.0 and key-based. Which one you use depends on how you’re going to use the API.

Chosing a method

If you are using the API to act on behalf of other users, you should use OAuth 2.0, otherwise, opt for the simpler key-based auth.

OAuth 2.0 Method

OAuth 2.0 allows you to act on behalf of users via a permissions system using scopes.

To begin using OAuth 2.0 you must register your application (or “client”) by providing its name and a callback URL. The callback URL must be the exact location you want users to be redirected back to your site after they see the Authorize Application prompt.

Registered applications receive a client ID and client secret, both of which must be used in one of the following flows to retreive an access token. This access token can then be sent with future requests to authenticate as that user.

Retreiving an Access Token

There are a couple of ways to retreive an access token:

  • Authorization Code Grant: should be used with OAuth clients running on a backend server
  • Implicit Grant: should be used with OAuth clients running on a frontend server (e.g. JavaScript clients)

Authorization Code Grant flow

This flow should be used by applications running on a backend server. It must not be used on frontend systems as that would expose your application’s client secret. The benefit of this grant type is a longer-lived Access Token.

Step 1: Authorization Code link

Your application must redirect the user to an Authorize Application page. This link is formed of many parameters specific to your application and the permissions required:

https://chew.tv/oauth/authorize?response_type=code&redirect_uri=callback_url&client_id=client_id&scope=scopes&state=state
response_type=code
Specify we want an auth code granted token
redirect_uri=callback_url
The exact callback URL registered to your application
client_id=client_id
The client ID value displayed underneath your registered app’s name
scope=scopes
Comma separated list of desired authorization scopes
state=state
A random string (for security, optional)
Step 2: Authorization Gateway

Once redirected, the user will be presented with an authorization prompt. From here they can see which scopes your application has requested and choose to authorize or cancel the request.

If accepted, they will be redirected to your callback URL with two parameters appended to the query string:

callback_url?code=auth_code&state=state

Because the user has been directed to your application, it now has access to these parameters via the request information. At this point, you should verify that the state variable returned matches the value you set in the URL you redirected the user to (if used).

Step 3: Swap Auth Code for Access Token

Finally, using the auth_code received above, your application can request an access token for the user. This must be a POST request to the access token endpoint, with the following parameters:

https://chew.tv/oauth/access_token?grant_type=authorization_code&redirect_uri=callback_url&client_id=client_id&client_secret=client_secret&code=auth_code
grant_type=authorization_code
Because we are exchanging an authorization code
redirect_uri=callback_url
The exact callback URL registered to your application
client_id=client_id
The client ID value displayed underneath your registered app’s name
client_secret=client_secret
The client secret value displayed underneath your registered app’s name
code=auth_code
The code received from the redirect URL in Step 2

If correct, the response body will be a JSON object including the desired access_token:

{ "access_token": "JrQx3wl8uWphpezTzcCRze4vzHIDJWxVvhrS2XR", "token_type": "Bearer", "expires_in": 94608000 }

Implicit Grant flow

This less secure flow should only be used by applications running on a frontend server. This approach doesn’t use your application’s client secret as it would be exposed by frontend code.

Step 1: Implicit Authorization link

Your application must redirect the user to an Authorize Application page. This link is formed of many parameters specific to your application and the permissions required:

https://chew.tv/oauth/authorize?response_type=token&redirect_uri=callback_url&client_id=client_id&scope=scopes
response_type=token
Specify we want an implicitly granted token
redirect_uri=callback_url
The exact callback URL registered to your application
client_id=client_id
The client ID value displayed underneath your registered app’s name
scope=scopes
Comma separated list of desired authorization scopes
Step 2: Authorization Gateway

Once redirected, the user will be presented with an authorization prompt. From here they can see which scopes your application has requested and choose to authorize or cancel the request.

If accepted, they will be redirected to your callback URL with the access token appended in the HTTP fragment/hash:

callback_url#access_token=JrQx3wl8uWphpezTzcCRze4vzHIDJWxVvhrS2XR&token_type=Bearer&expires_in=604800

Because the user has been directed to your application, it now has access to these parameters (e.g. via window.location.hash in JavaScript).

Using an Access Token

To authenticate as the user via their access token it must be sent in a HTTP Bearer Authorization header along with every API request:

Authorization: Bearer JrQx3wl8uWphpezTzcCRze4vzHIDJWxVvhrS2XR

Authorization Scopes

Your application can request differing levels of access to users’ accounts. We recommend you only request the minimum access your application needs to function.

The currently available scopes are:

email
A user’s email address
private
A user’s private shows
read
A user’s public information and shows
write
Ability to create, edit, delete and stream shows

API Key Method

This method of authentication is much simpler than OAuth 2.0 but allows full access to your own account. To act on behalf of other users you must use OAuth 2.0 instead.

Retreiving an API Key

You can generate an API Key from the developer section of your account.

Warning: This key provides full access to your account and should not be shared with anyone, nor should it be exposed in any client-side code.

Using an API Key

To authenticate with your API Key it should simply be appended as a parameter named key to all requests. For example:

https://api.chew.tv/v1/shows?key=SjF1ECtyDanaqZ1ojSaOkimWm3hAWjAxS2T5igm