Overview

Currently we support the OAuth 2.0 (OIDC) Auth Code flow with Access Token, Refresh Token, and ID Token as grant types. Our implementation is fully OIDC-conformant.

Should you require another flow please reach out to our API support team (developer@mediavalet.com) with details of how and why you'd like to use the flow. We do not support the Resource Owner Password Credentials Grant due to its inherent insecurity.

The base URL for all authentication requests is https://iam.mediavalet.com

Prerequisites

You'll require client_id, client_secret, and redirect_uri values that are setup by our API support team to authenticate. These should be issued when access is granted to the API. If they haven't been please contact our API support team(developer@mediavalet.com) for assitance.

How to Authenticate using the Auth Code Flow

  1. Make the initial authorization request to start the flow
    Example Request
    GET https://iam.mediavalet.com/connect/authorize
    ?client_id=xpto_example
    &response_type=code
    &scope=openid%20api
    &redirect_uri=https%3A%2F%2Flocalhost%3A8080
    &state=state-296bc9a0

  2. At this point your browser will be re-directed to our secure login page where the user fills in their credentials which are validated by our identity service.
  3. Our identity service will now redirect the user's browser to the provided redirect_uri with the code as a query parameter(we will only re-direct to the redirect_uri you've registered that's associated with your client id)
    Example Request
    GET https://localhost:8080
    ?client_id=xpto_example
    &code=0357a6f78e400d4039eacfdf3007d5b8d6984c9d92a0175fc5ed6f8cc1cec472
    &scope=openid%20api
    &state=state-296bc9a0
  4. Your client application then makes a request to the POST /connect/token endpoint with the data below form encoded in the body of the request. This should be done from a secure service, since it requires your client_secret, and is handling access tokens.
    Example Request
    POST https://iam.mediavalet.com/connect/token

    grant_type=authorization_code
    &code=3ed822db0c2409dd1babee5150e8ec71dcf854534214fb3a9361ada778a62ea1
    &redirect_uri=https%3A%2F%2Flocalhost%3A8080
    &client_id=xpto_example
    &client_secret=5150e8ec71dcsecretf85453421
    Example Response
    {
      "id_token":"ID_TOKEN_VALUE",
      "access_token":"ACCESS_TOKEN_VALUE",
      "expires_in":3600,
      "token_type":"Bearer"
    }
  5. You can now use the token provided in the "access_token" parameter to authorize requests to our API by providing an Authorization header with each request that includes the token.
    API Header Example
    Authorization: bearer ACCESS_TOKEN_VALUE

Refreshing Access Tokens

A refresh token is a special token that is used to generate additional access tokens. This allows you to have short-lived access tokens without having to collect credentials every single time one expires. You request this token alongside the access and/or ID tokens as part of a user's initial authentication flow.

How to Use a Refresh Token

To refresh your access token as well as an ID token, you send a token request with a grant_type of refresh_token.
Example Request
POST /connect/token HTTP/1.1
Host: iam.mediavalet.com
Content-Type: application/x-www-form-urlencoded
cache-control: no-cache

grant_type=refresh_token&refresh_token=9d03ba84f34
&client_id=example&client_secret=example
Example Response
{
  "id_token":"ID_TOKEN_VALUE",
  "access_token":"ACCESS_TOKEN_VALUE",
  "refresh_token":"NEW_REFRESH_TOKEN",
  "expires_in":3600,
  "token_type":"Bearer"
}

Endpoint Descriptions

Authorize Endpoint (/connect/authorize)

This is a starting point for browser-based OpenID Connect flows such as the authorization code flow. This request authenticates the user and returns tokens along with an authorization grant to the client application as a part of the callback response.

Request Parameters
Parameter Description
client_id Identifies the client and must match the value pre-registered with MediaValet.
redirect_uri Callback location where the authorization code or tokens should be sent to. It must match the value pre-registered with MediaValet during client registration.
response_type Any combination of code, token, and id_token. The combination determines the flow.
scope “openid” and “api” are required for authentication requests. The later adds all claims that the MediaValet API expects to complete a request. “offline_access” is optional and should be used to request refresh tokens.
state A value to be returned in the token. The client application can use it to remember the state of its interaction with the end user at the time of the authentication call.

Token Endpoint (/connect/token)

This endpoint returns access tokens, ID tokens, and refresh tokens, depending on the request parameters. For refresh token flow, calling /token is the only step of the flow. For the authorization code flow, calling /token is the second step of the flow (/Authorize being the first one).

Request Parameters
Parameter Description
client_id Identifies the client and must match the value pre-registered with MediaValet.
client_secret This client secret is used in conjunction with client_id to authenticate the client application.
code The value is what was returned from the authorization endpoint. The code has a lifetime of 60 seconds.
grant_type Can be one of the following: authorization_code or refresh_token. Determines the mechanism MediaValet uses to authorize the creation of the tokens.
redirect_uri Required when grant_type is authorization_code. Specifies the callback location where the authorization was sent. This value must match the redirect_uri used to generate the original authorization_code.
refresh_token Required when grant_type is refresh_token. The value is a valid refresh token that was returned from this endpoint previously.
Response Properties
Parameter Description
access_token Access token that can be used against the MediaValet API on behalf of an user.
expires_in The expiration time of the access token in seconds.
refresh_token An opaque refresh token. This is returned if the offline_access scope is granted.
id_token An ID token. This is returned if the openid scope is granted.