Authentication

Authentication

Overview of security and authentication for the MediaHound domain.

Overview

Applications will be granted a client_id and a client_secret through our developer portal. In order to make authorized calls to MediaHound’s API, your application must first obtain an OAuth access_token. The way you will obtain such tokens will depend on your use case.

Security Flows

NameUse Case
Client-Credentials GrantYou need only an access_token and have no need for Users to authenticate.
Implicit GrantYou need Users to authenticate and are building an Application where your client_secret is not secured and may get leaked (iOS, JavaScript, etc.).
Code GrantYou need Users to authenticate and are building a Server-Based Application where your client_secret is secured and will not get leaked.
Password GrantYou need Users to authenticate, need the User's Password, and are explicitly approved for Password Grant.

Using Access Tokens

  • An access_token exists independently. This means that an application may request as many tokens as it wants.
  • An access_token expires after 2 weeks or less, depending on the current state of the client_id. The time-to-live is centralized to the client_id, so every 2 weeks, all tokens for a given client_id are expired.
  • Rate limiting will be applied on a client_id level, not an access_token level. This means that if 2 tokens are retrieved for a single client_id, once all tokens cumulatively reach the rate limit established for the client_id, they all become temporarily blocked until the rate limit window is reset.

There are 2 ways to use an access_token. Either as a query param attached to each request:

Copy
http
?access_token={access_token}

or as a Bearer Authorization Header attached to each request:

Copy
http
Authorization: Bearer {access_token}

Scopes

Scopes are used when authenticating a User and act as a permission for things to do on behalf of the User. The Application specifies which scope permissions they would like to ask the User for. Not all scopes are available to all Applications. Below is a summary of all the scopes that are available to be requested by the Application to the User:

The current security implementation shows all scopes that are being requested by the Application to the User, and the User can either accept all of them or deny all of them. There is no current capability for the User to toggle certain scopes off. So, as an Application, only request scopes that are absolutely needed for your use-case, or risk a User denying you access.

Scopes

ScopeGrants Permission to...
public_profileRead the User's public profile, such as username and image.
user_followsRead what the User currently follows.
user_likesRead what the User currently likes.
user_collectionsRead the User's Collections.
user_actions.likePerform likes and unlikes on behalf of the User.
user_actions.followPerform follows and unfollows on behalf of the User.
user_actions.postMake posts on behalf of the User.
user_actions.new_collectionCreate new Collections on behalf of the User.
user_actions.update_collectionUpdate current Collections of the User.
user_feedRead the User's Interest Feed.
user_suggestedRead customized suggestions and recommendations for the User.