Server Authentication Flow

Register your application

First, register your client application with MediaCore.

You’ll need to know your client_id and client_secret later in the process, so be sure to store them somewhere safe.

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, redirect the user to the authorization endpoint.

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 code.
  • 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.
  • access_type – Optionally set this to offline if you would like to receive a refresh_token. See Using refresh tokens for details.
  • 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 Request:

In order to request authorization, your application should issue the user a redirect response like this:

HTTP/1.1 302 Found
Location: https://pacificu.mediacore.tv/api2/oauth/authorize?
  response_type=code&
  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 query string.

Verify the response

If this request is valid, the redirect URI will include the same state query 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 code parameter in the query string.

Query parameters:

  • code – A temporary authorization code that your client can exchange for an access_token in the next step.
  • state – This is expected to be the same state value that the client passed in the query 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?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz HTTP/1.1
Host: client.example.com

Once you have verified the response and you have the code, you can proceed to Exchange the code for an 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 query string.

Query 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 query 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: client.example.com

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

Exchange the code for an access_token

Once you have an authorization code, you can exchange it for an access_token by making a direct request from your application to the MediaCore API.

Token Request

Json Parameters:

  • grant_type – Must be authorization_code.
  • code – The code from the previous step.
  • redirect_uri – The redirect_uri that you specified in the original authorization request. If this does not match exactly, the access_token will not be given.
  • client_id – Your client ID that was assigned when you registered your application.
  • client_secret – Your client secret key that was assigned when you registered your application.

Example request:

POST /api2/oauth/access_token HTTP/1.1
Host: pacificu.mediacore.tv
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "SplxlOBeZQQYbYS6WxSbIA",
  "redirect_uri": "https://client.example.com/cb",
  "client_id": "ff20303a-ed9c-4337-8016-9319bfa02a1b",
  "client_secret": "56f759ca-1639-4418-92ce-98451f2f9983"
}

Note

This request may also use application/x-www-form-urlencoded as the Content-Type.

Token Response

If the exchange request succeeds, the response will include your access_token and some related metadata.

Response parameters:

  • token_type – This will be set to bearer.
  • access_token – The token that you can use to authenticate API requests.
  • expires_in – The number of seconds that the access_token will continue to be valid.
  • refresh_token – A token that can be exchanged for a new access_token once the access_token has expired. This parameter will only be included if access_type was specified as offline in the request.
  • scope – The authorized permissions. Note that this may differ from the requested scope, because we may allow the user to grant only some of the requested permissions.

Example response:

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

{
  "token_type": "Bearer",
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "[...]"
}

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 and then repeat the request.

There are two ways to request a new token:

  1. Repeat the authorization flow. This is only an option if the user is still actively using your application, because you must be able to redirect the user back to the authorization page.
  2. Exchange a refresh_token for a new access_token. See Using refresh tokens for further details.

Using refresh tokens

Refresh tokens should be used when your application needs to be able to make API calls on behalf of a user even after that user is no longer online and actively using your application. This use case is called offline access.

In order to receive a refresh token, offline access must be requested in the initial Authorization Request. Once enabled, a refresh_token will accompany the access_token that your application receives in Exchange the code for an access_token. You must store this refresh_token some place safe!

Refresh Request

Json Parameters:

  • grant_type – Must be refresh_token.
  • refresh_token – The refresh_token you have received.
  • client_id – Your client ID that was assigned when you registered your application.
  • client_secret – Your client secret key that was assigned when you registered your application.

Example request:

POST /api2/oauth/access_token HTTP/1.1
Host: pacificu.mediacore.tv
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "tGzv5JOkF0XG5Qx2TlKWIA",
  "client_id": "ff20303a-ed9c-4337-8016-9319bfa02a1b",
  "client_secret": "56f759ca-1639-4418-92ce-98451f2f9983"
}

Refresh Response

If the refresh request succeeds, the response will include your new access_token.

Response parameters:

  • token_type – This will be set to bearer.
  • access_token – The token that you can use to authenticate API requests.
  • expires_in – The number of seconds that the access_token will continue to be valid.
  • refresh_token – A new refresh_token that supercedes the one used in this request.
  • scope – The authorized permissions. Note that this may differ from the requested scope, because we may allow the user to grant only some of the requested permissions.

Example response:

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

{
  "token_type": "Bearer",
  "access_token": "VbcNSIuLuKml4bvmGOlfwb",
  "expires_in": 3600,
  "refresh_token": "ABJiRQJZtA6v3pBJinBhWm",
  "scope": "[...]"
}

Now that you have a new access_token, you can continue making API requests on behalf of the user.