Authentication

Password Grant

Password Grant is an OAuth flow where an Application has and needs direct access to the User's password.

This flow can only be used by pre-approved Application keys. If you think you need to use this flow, please contact MediaHound.

Request Token

Make a request to the MediaHound security services with the Application's client_id and client_secret along with the User's username and password.

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

Request Parameters

NameDescription
grant_typeValue should be password, specifying that the Application is initializing a Password Grant flow.
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.
usernameThe User's username.
passwordThe User's password.

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==

If you try to use this flow and are not allowed, you will get the following response:

Copy
JSON
{
  "error" : "invalid_client",
  "error_description" : "Unauthorized grant type: password"
}

If the request is successful, 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.