1. Register your integration

First you must register your integration by creating a ticket on https://support.zeticon.com, or by emailing support@zeticon.com.

Your request must include the following information:

• Company name / publisher

• Name of your integration

• Description of your integration

• Destination server(s)

• Redirect-URL(s)

After we review your application, you will be sent a client_id and a client_secret which you can then use in the OAuth2.0 flow.

For this setup guide assume the following data. Swap out the data in the examples for your own values.

2. Obtaining a token

Client Credentials Grant a.k.a. interactive flow.

Redirect user to the MediaHaven Authentication Portal

Let's assume we want to connect to https://integration.mediahaven.com. For your actual connections, change the URL accordingly.

Kick-off the authorization flow by redirecting the user/browser to

https://integration.mediahaven.com/auth?client_id=882rgLgNTSqwBSnUUbC3qRiUfMGhorzZ

The user will be greeted by a MediaHaven login screen where he can login with one of the configured login options. Once logged in, the user will need to grant your app access to his account.

Open

Open

If the user clicks the "Authorize" option he will be redirected back to your initially registered Redirect-URL, with the Authorization code as query parameter:

https://demo-app.com/redirect?code=OORO1gjyWP7Mr9ztl2Dvp06NjR2kTApc

If you have multiple redirect_uri’s registered, you need to supply the correct one using the redirect_uri query parameter.

Swap Authorization code for an access token.

On your end, you would read the code query parameter from the URL and use it to obtain the access token.

The authorization_code can only be used once, and is only valid for a limited amount of time.

To obtain an actual access_token you would make a POST request to the following endpoint, and supply the code, client_id, client_secret and grant_type=authorization_code parameters

https://integration.mediahaven.com/auth/oauth2/token

Below is an example of the request with cURL. 

If all goes well, you'll receive a  status 200 with the following JSON:

Resource Owner Password Credentials

The Resource Owner Password Credentials grant is used when the application exchanges the user’s username and password for an access token.
This is something strongly advise not to use, but can be used.

 To obtain an access_token you would make a POST request to the following endpoint, and supply the code, client_id, client_secret , username and password parameters.

https://integration.mediahaven.com/auth/ropc.php

Below is an example of the request with cURL. 

If all goes well, you'll receive a  status 200 with the following JSON:

3. Using the token

You can then use the access_token when making requests to the Rest-API by setting it in the Authorization header:

If you use the wrong token, or the token is expired, you will get a 401 response. You would then use the refresh token to obtain a new token.

4. Using the refresh token

The refresh token typically has an expiry date much further in the future. You can use this to obtain a new set of tokens.

You make a similar POST request as when requesting the token, but this time you supply the refresh_token and grant_type=refresh_token parameters.

If all goes well, you will get a 200 status code with a new access_token and refresh_token. The previous access_token and refresh_token will be invalid.

If the response returns a 401 Unauthorized, that means that the refresh_token has expired or your App permissions have been revoked. You would then start the flow back from the beginning.

5. Token introspection

The token introspection endpoint allows you to get the current status of a token.

To request the information, send a POST request to the following URL https://integration.mediahaven.com/auth/introspect.php . It requires BASIC Auth with client_id as username and client_secret as password. Secondly, it also requires the token as post parameter.

Response

The response will be as follows

6. Supported combinations