Client/JS Authentication Flow

Register your application

First, register your client application with MediaCore.

You’ll need to know your client_id later in the process, so be sure to store them somewhere safe. (There is no client_secret for native applications because it would be impossible to keep it secret.)

You’ll also need to configure the redirect URIs for this client. When a user authorizes your client, they will be redirected to one of these URIs with the pertinent details.

Request authorization

When your client application needs to make API calls on behalf of an end-user, you must direct the user to the authorization endpoint in a browser window.

Once the user reaches this endpoint, two things happen:

  1. The user will be asked to log in, if they aren’t already.

  2. The user will be shown an authorization consent form, with the option to either approve or deny the authorization request.

    On this page, MediaCore will clearly show the user:

    • what application is requesting to access our API on their behalf;
    • what permissions the client has requested (via the scope); and
    • whether the application has requested longer-term “offline” access, meaning that the application can continue to access the API on the user’s behalf without the user having to re-authorize in the future (also via the scope).

There are a number of parameters that should be set when redirecting to the authorization endpoint.

Query parameters:

  • response_type – Must be set to token.
  • client_id – Your client ID that was assigned when you registered your application.
  • redirect_uri – The callback URL where the user should be redirected once they have approved or denied your authorization request. This must exactly match one of the redirect_uris that you configured when registering your client application.
  • scope (optional) – The permissions to request from the end-user. See Scopes for a list of supported values.
  • state – An unguessable random string that will be mirrored back to the client in the redirect response. The client must store this value so that it can verify that the same state is passed back in the redirect URI, thereby mitigating CSRF attacks.

Example:

In order to request authorization, your application should redirect the user to MediaCore with a javascript snippet like this (line breaks added for readability):

window.location = 'https://pacificu.mediacore.tv/api2/oauth/authorize?
  response_type=token&
  client_id=s6BhdRkqt3&
  redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb&
  scope=one%20two&
  state=xyz';

Handle the response

Once the user submits the authorization form, they are sent back to the redirect_uri (specified in the last step) using a 302 Found redirect. Everything you need to know will be included in the fragment of the URL (not the query string).

Verify the response state

If this request is valid, the redirect URI will include the same state fragment parameter as was provided in the last step. The client must verify that the same state that was sent in the authorization request has been mirrored back in this response.

If the state does not match, no further processing of this request should occur, and the client must show a stock error message to the user. Do not trust any of the request parameters.

If authorization was granted

To check if the authorization request was approved, look for a access_token parameter in the fragment string.

Fragment parameters:

  • access_token – The access_token to validate in the next step.
  • state – This is expected to be the same state value that the client passed in the fragment string of the authorization request. This must be verified!

Example request:

When authorization has been granted, your application will receive a request from the user, similar to this:

GET /cb#access_token=2YotnFZFEjr1zCsicMWpAA&state=xyz HTTP/1.1
Host: localhost

Once you have verified the state and you have the access_token, you can proceed to Verify the access_token.

If authorization was denied

To check if the authorization request was denied or failed for some reason, check for an error parameter in the fragment string.

Fragment parameters:

  • error – An error code defined by the OAuth2 specification.
  • error_description – A human readable error message suitable for displaying to users. (Remember to escape this string if injecting it into an HTML document.)
  • state – This is expected to be the same state value that the client passed in the fragment string of the authorization request. This must be verified!

Example request:

When authorization has been denied, your application will receive a request from the user, similar to this:

GET /cb#error=access_denied&error_description=Something+went+wrong&state=xyz HTTP/1.1
Host: localhost

If an error occurred, this process stops and you must show an error message to the user.

Verify the access_token

Before the access_token should be used, it must be validated! Your client application must make an API call to MediaCore to ensure your application was the intended audience.

Example Request:

GET /api2/oauth/tokeninfo HTTP/1.1
Host: pacificu.mediacore.tv
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Cache-Control: no-store
Pragma: no-cache

Example Response:

HTTP/1.1 200 Ok
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "audience": "2YotnFZFEjr1zCsicMWpAA",
  "user_id": "1234",
  "scope": "...",
  "expires_in": 3600,
}

The client must ensure that the audience in this response matches its own client_id. If the audience does not match, this is a malicious request: the client must discard the token and show an error to the user.

Send API requests

Now that you have an access_token, your client can make API calls on behalf of the user.

To send an API request on behalf of the user, pass their access_token via the Authentication header. For example:

Example Request:

GET /api2/users/me HTTP/1.1
Host: pacificu.mediacore.tv
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

When an access_token expires

If you try to make an API request with an access_token that has expired or been revoked, you will receive a 401 Unauthorized response, similar to this:

Example Response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Bad credentials"
}

To recover from this error, your application should request a new access_token by repeating this authorization flow, and then repeat the failed request.