Authentication

Code Grant

The Code Grant is appropriate for Clients who can securely keep their client_secret and would like to interact with Users.

If you are unable to reliably secure the client_secret and access_token we provide after the completion of this flow, then Code Grant is not for you. Instead, try Implicit Grant.

Request Code

Make a request that will redirect to Login Pages hosted by MediaHound. These pages must be displayed in a Browser or WebView. As such, this flow will not work if the requests are made from a non-web backend server.

Copy
http
https://api.mediahound.com/1.3/security/oauth/authorize?client_id={client_id}&client_secret={client_secret}&scope=public_profile+user_likes&response_type=code&redirect_uri=http://localhost

Request Parameters

NameDescription
client_idThe Application's Client ID.
client_secretThe Application's Client Secret.
scopeThe scopes (+ delimited) that the Application is requesting the User to approve. A full list of available scopes can be found here.
response_typeValue should be code, specifying that the Application is initializing a Code Grant flow.
redirect_uriUpon completion of the login flow and permission grant of scopes by the User, we will redirect the User to this specified location. If the User has previously granted permission of the scopes to the Application, redirect will happen immediately after User login.

If an Application makes the request with scopes outside of its allowed scopes, redirect will occur with the following error information:

Copy
http
http://localhost/?error=invalid_scope&error_description=Invalid%20scope:%20user_likes&scope=public_profile

If the User rejects permission of the scopes to the Application, redirect will occur with error information:

Copy
http
http://localhost/?error=access_denied&error_description=User%20denied%20access

Finally, if the flow is completed and the User grants all permission of the scopes to the Application, redirect will occur with a code:

Copy
http
http://localhost/?code={code}

Request Token

Parse out the code and make a request to get an access_token. The code is one-time use and should not be stored.

Copy
cURLHTTPieJava
curl -X POST -vu {client_id}:{client_secret} https://api.mediahound.com/1.3/security/oauth/token -H "Accept: application/json" -d "code={code}&redirect_uri=http://localhost&grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}"

Basic Authorization Header

This request requires an Authorization header with Basic authentication. Several command line tools do this automatically, as can be seen in the examples above. For those unfamiliar with this, it means that the client_id and client_secret need to be put together and colon ( : ) separated, then Base64 encoded. This value must then be placed after "Basic " and this entire string will be the value of the Authorization header. For example, if your client_id were "MyClientId" and your client_secret were "MyClientSecret", then the Base64 encoded header would look like this:

Copy
http
Authorization: Basic TXlDbGllbnRJZDpNeUNsaWVudFNlY3JldA==

Request Parameters

NameDescription
client_idThe Application's Client ID.
client_secretThe Application's Client Secret.
codeThe code parsed out from the previous redirect.
redirect_uriThis must match the value of redirect_uri in the first request.
grant_typeValue should be authorization_code since you are in the Code Grant flow.

Upon a successful request, the response will be:

Copy
JSON
{
  "access_token": String,
  "expires_in": Long,
  "refresh_token": String,
  "scope": String,
  "token_type": "bearer"
}

Response Parameters

NameDescription
access_tokenThe actual token to use on subsequent requests.
expires_inNumber of seconds until the token expires.
refresh_tokenThe token to be used upon expiration of the access_token in order to request a new one.
scopeAll the default scopes that the Application is allowed to request.
token_typeValue would be "bearer" since the token being returned is to be used as a Bearer Token.

Securely save both the access_token as well as the refresh_token.

Details about and how to use the access_token can be found here.

Refresh Token

This request uses the same Basic Authentication Header described above. Once the access_token has expired, a request can be made to refresh it using the refresh_token:

Copy
cURLHTTPieJava
curl -X POST -vu {client_id}:{client_secret} https://api.mediahound.com/1.3/security/oauth/token -H "Accept: application/json" -d "refresh_token={refresh_token}&grant_type=refresh_token"

Upon success, the response will look identical to the response for Request Token. Refresh Token can be repeated each time the token has expired.