Which authentication workflows are supported by the API?






  • We support the OAuth 2.0 (OIDC) Auth Code Flow and Resource Owner Password Flow authentication mechanisms at this time. Our implementation is fully OIDC-conformant. 

    • Auth Code Flow involves exchanging an authorization code for a token. This workflow is recommended when building out a secure application integration as the application's authentication methods are included in exchange and are kept secure.
      Code Flow First Part

      As this is a redirection-based workflow, the third-party client must be capable of interacting with the resource owner's user-agent (i.e. a web browser) and capable of receiving incoming requests from MediaValet's authorization server. 

      More information on this workflow can be found in the links below
    • Resource Owner Password Flow allows for the exchange of the username and password of a user for an access token and optionally, a refresh token. 
      Resource Owner Password flow: Step-by-step

      While we do discourage using this workflow as the default authentication mechanism for security reasons (the resource owner's password is exposed to the application), this is the preferred method for enforcing a non-interactive authentication workflow.

    • (COMING SOON!) Our team is also working towards building the Client Credentials Flow which will be the preferred authentication method once implemented. 




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 latter 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 a 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.



Was this article helpful?
0 out of 0 found this helpful