Mediaconnect API Reference (09.10.2024)

Download OpenAPI specification:Download

Introduction

ConnectID is a solution for user authentication, authorization and payment for web pages and apps. ConnectID is made by Mediaconnect AS.

Parties

The main parties using ConnectID are:

  • Partners: The organization publishing a web site, an app, a newspaper, a magazine, a newsletter or any other information users shall have access to. A partner will often have only one site, but may have many.
  • Clients: A client is a third-party website or app that uses ConnectID. A client may serve information for one or more newspapers, magazines, newsletters or other similar products. It may also have discussion forums and other services a user is able to access. The information may be available without a login or require a login. It may be available free or only if paid for. The services described here makes login (authentication) and user authorization available to a site to make it able to present only the authorized information to any user. Each client must have a unique clientId.
  • Users: Any end user with access to information. This may be a reader, a subscriber or someone who orders something. It may also be someone who takes part in a discussion and where it necessary to log in before posting.

API-lifecycle

The stages in API lifecycle are listed in chronological order below:

  • Proposed: A endpoint is defined and will be implemented soon.
  • In Test: The latest version of the endpoint is now ready for test and is available in our test environment.
  • In Production: The latest version of the endpoint is now in production, and is available in our producation environment.
  • Deprecated: The endpoint is now deprecated, and will be removed from our test and production environment in 180 days (6 months). Do not use this endpoint for future software development.
  • Deprecated Warning: The endpoint has previously been deprecated and will be sunset soon. The endpoint will be removed in 30 days.
  • Ready for sunset: The endpoint will be sunset and will not be usable after the sunset. The endpoint will be removed in 10 days.
  • Sunset: The endpoint is now sunset. The endpoint is now not able to be used and has been removed from our test and production environment.

You can read more about the API-life cycle on our knowlegde base.

Versioning and changelog

Versioning

The services will be regularly upgraded. As a general rule this should not be an issue for the client. All existing elements will be present in new versions. New elements may be added. Your application may safely ignore new elements. If there are major changes to a service it will normally be developed as a new endpoint with the new / changed functionality. The old version will be available to other clients that are not upgraded to the latest version. New clients should always use the newest version. Services may be dropped if there are no known clients using it or if the service is not compatible with changes to the core system. Client developers will be notified if this should happen.

Changelog

We have a webpage to show the changes on this API-documentation. You can see the changelog on Mediaconnect API changelog.

Knowlegde Base

We have described how to use the APIs for some use cases on our Knowlegde Base. Here you may read about:

ConnectID specifications

URLs

ConnectID can be used with new domain servers, which one have better names and link structure. For now there are two different servers for Norway and Sweden.

  • connectid.no
  • connectid.se

There are currently two types of servers in use, namely the loginServer and the apiServer.

loginServer

apiServer

Configuration for new client in ConnectID

The minimum configuration to create a new client in ConnectID are listed below:

  • Client logo
  • Client background
  • Name
  • Name description
  • Homepage URL
  • Customer Care phone number
  • Customer Care e-mail address
  • Product
  • Subscription terms url
  • User terms url

Its very important that client logo is in a good quality. Best if has transparency when needed. Acceptable formats are:

  • .svg
  • .png
  • .jpg

Dimension of the logo image should be at least (for best view):

  • width: 318 px
  • height: 64 px

Client background

In ConnectID client can customize background that is displayed behind the gui. It should be ratter big like 2835x2126 px. Background is displayed as a “cover” for whole window. Information about size and way to display are specified in custom.css.

custom.css:

It is possible to introduce new look using custom.css. Here can be override all other styles, background images, fonts etc. which one are used in standard login.css.

Default custom.css:

.customerNumberExplanationLabel { font-weight: bold; }
.customerNumberExplanationAnswer { margin-top:5px; display: block; }
.acceptTermsLabel { display: inline; }
.acceptTermsLabel INPUT { margin-left:30px; }

.customerNumberExplanation { margin: 1em 0; }
.customerNumberExplanationImage { height:50px; width: 150px;
    background-color: #ddd; border: 2px #888 dashed; display:block; }

.guiVersion2 body {
    background-size: cover;
    background-position: center center;
    background-repeat: no-repeat;
    background-image: url(./connectid_background_oslo.jpg);
}

For example can be easy changed colors of the headings…

.guiVersion2 .heading {

    text-align:center; font-size:150%;
    border-color: #029675;
    border-width: 1px 0;
    border-style: solid;
    color: #029675;
    padding: 16px 0;
    font-weight: normal;
}
.guiVersion1 .heading { display:none; }

About OAuth 2.0

OAuth is an open standard to authorization. OAuth provides client applications a ‘secure delegated access’ to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

A technical specification of OAuth 2.0 is described in the standard RFC 6749. A non-technical simple specification is given in this guide and Wikipedia.

Authorization endpoint

This endpoint ensures that the user is logged in and has authorized access to the desired resource. It returns an authorization code as per the OAuth specification. If the user is not already logged in, she will be presented with the same GUI as the loginUrl.

Authorization grant types

We are supporting two types of Authorization grant types:

  • Authorization code
  • Client credentials (used for client API).

Authorization code

The authorization token is provided by the authorization endpoint and is used with the token endpoint to get an access token.

Token endpoint

The token endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token. The token endpoint is used with every authorization grant except for the implicit grant type (since an access token is issued directly). See the OAuth specification.

Access token

The access token is provided by the token endpoint and is required in order to access the ConnectID APIs.

Extension grant types

The OAuth2 specification allows for extension grant types to be created (see section 4.5 in RFC 6749). Mediaconnect has created a proprietary grant type to enable the token endpoint to issue tokens using the state code given by the External Identity API. In order to use the custom grant type the client must POST to the token endpoint using the following parameters (for External Identity API):

Parameter Value
grant_type https://connectid.no/oauth2/grant_type/extid_code
code Set the value from the field extidCode in External Identity API

The request should be sent as application/x-www-form-urlencoded and authenticated using Basic Authentication. The response is a standard OAuth2 response according to the specifications in RFC 6749.

About the API

The WebServices provided by Mediaconnect are developed as a REST-like API, see this wikipedia article about REST will give you an introduction to REST. Most modern programming languages have support for consuming REST services or have libraries that can be used.

Access the API using the apiServer

This server hosts the APIs. It has the following address:

Response header

A response header is used to provide additional information. We are using following custom response header.

Response header Description
X-Mediaconnect-Api-Version The project version this response is based upon
X-RateLimit-Remaining A rate limit is the number of API calls you may do within given time period. If this rate limit is exceeded, your API-calls will be throttled. The number of request remaining before encountering a 429 too many request error.

Our default rate limit for a client is:
• 100 API calls for a second.
• 2000 API calls for a minute.
X-RateLimit-Reset A rate limit is the number of API calls you may do within given time period. If this rate limit is exceeded, your API-calls will be throttled. The remaining epoch seconds before the rate limit resets. Renew every 60 seconds.

About the Client Mode

Some API endpoints are available to the client without an access token created by the user. Instead the client can request an access token on behalf of the client itself. Some of the services described under this section may be cached by the client for a limited time. The resources will in many instances be quite static, but changes may happen at any time. A long cache timeout can be used if the partner can invalidate the cache on demand.

Access the API using the apiServer:

About the URLs

GUI flows describe transitions between different GUI states. Some states visible to the user and wait for user input while other states are only for computation and immediately trigger events for transitioning to other states. Transitions between states are caused by events and flows may specifiy that certain states should be selected when certain events are triggered. If an event is not mentioned anywhere in the flow then the next state will be selected. For example, a continueEvent usually has no specific state connected to it but instead causes the next state to be selected.

Sequences are fragments of a flow that can be re-used in different URLs, like the simpleAuthenticationSequence. Sequences and states can be used interchangably in flows, as both result in new events being triggered. The difference is that for a sequence, some events will be handled internally in the sequence. Only events which are not handled internally in the sequence will cause a transition to a state outside the sequence.

Access the URLs using the loginServer.

GUI: createUserUrl

You can redirect a user’s browser to this URL in order to ensure that the user has a ConnectID account and is logged in.

If the user already is logged in with the specified credential, or the user already is logged in and no credential parameter is specified, then the user’s browser will immediately be redirected back to the returnUrl.

Otherwise, the user is asked to log in using a one time password but can also log in using an existing ConnectID account or create a new account. The credential field will have the value of the credential parameter when the GUI is shown, but the user can edit this field and thus log in with a different credential.

If the user already is logged in with a different credential then the user will be logged out from that credential and logged in with the new credential. If the user leaves the the remember me option checked then the rememberMeCookie for this client will be set according to the new credential. If the the user unchecks the the remember me option but a rememberMeCookie exists for this client then that cookie will be not be removed.

This URL behaves similarly to the loginUrl but is better suited if it is likely that the user does not already have a ConnectID account.

  • Server: loginServer
  • Relativ path: createUser
  • Method: GET
URL parameters Description Required
clientId The unique ID of the client, e.g. no.mediaconnect.test
returnUrl A URL to redirect the user’s browser back to on success (the user will be logged in)
errorUrl A URL to redirect the user’s browser back to if something goes wrong (the user might not be logged in)
credential If specified, the credential field will have this value when the GUI is shown but will still be editable by the user (however, no GUI will be shown if the user already is logged in with this credential or if the user already is logged in and this parameter is not specified)
credentialSubmit If this parameter is set (credentialSubmit=true) will be submit the form with credential given as credential parameter.
assumeNewUser If true then ask for verification code password first, if false then ask for account password first. Default true for this URL.

GUI: loginUrl

You can redirect a user’s browser to this URL to let the user log in.

If the user already is logged in with the specified credential, or the user already is logged in and no credential parameter is specified, then the user’s browser will immediately be redirected back to the returnUrl.

Otherwise, this URL works just like the oauthAuthorizationEndpoint except that it does not return an oauth authentication code to the caller. The user can either log in using an existing ConnectID account or create a new account. The credential field will have the value of the credential parameter when the GUI is shown, but the user can edit this field and thus log in with a different credential.

If the user already is logged in with a different credential then the user will be logged out from that credential and logged in with the new credential. If the user leaves the the rememberMeCheckbox checked then the rememberMeCookie for this client will be set according to the new credential. If the the user unchecks the the rememberMeCheckbox but a rememberMeCookie exists for this client then that cookie will be not be removed.

This URL behaves like the createUserUrl but is better suited if it is likely that the user already has a ConnectID account.

URL parameters Description Required
clientId The unique ID of the client, e.g. no.mediaconnect.test
returnUrl A URL to redirect the user’s browser back to on success (the user will be logged in)
errorUrl A URL to redirect the user’s browser back to if something goes wrong (the user might not be logged in)
credential If specified, the credential field will have this value when the GUI is shown but will still be editable by the user (however, no GUI will be shown if the user already is logged in with this credential or if the user already is logged in and this parameter is not specified)
assumeNewUser If true then ask for verification code first, if false then ask for account password first. Default false for this URL.

URL: azure

This url is used to setup an already logged in connectid user for azure active directory (Microsoft Entra ID). This only works if the user is already logged in, there exists a configuration for azure active directory, if the user havent already registered for this service, that the user is registered in their respective azure active directory tenant.

  • Server: loginServer
  • Relativ path: azure/{id}?returnUrl={returnUrl}
  • Method: GET
URL parameters Description Required
id The id for which is the configuration to use for this process.
returnUrl A URL to redirect the user’s browser back to. If success (the user will be logged in and validated for azure active directory access) this will be {returnUrl}/callback?azureStatus=success. If something went wrong (error occured) this will be {returnUrl}/callback?azureStatus=error.

URL: logout

You can redirect a user’s browser to this URL to log the user out. This will invalidate the user’s ConnectID session so that the user must log in on the next visit to this client (and to other clients which do not have rememberMeCookies).

If the user did not uncheck the rememberMeCheckbox during a previous login to this client and therefore has a rememberMeCookie for this client then this rememberMeCookie will also be removed.

However, rememberMeCookies for other clients will not be removed. If the user logs out from the client specified by the clientId parameter (let’s call that client A) but has a rememberMeCookie for another client (client B) and visits client B after logging out from client A then the user’s ConnectID session will be recreated. If the user then visits client A again before the ConnectID session expires (20 minutes) then the user will be automatically logged back in to client A.

If a user is using a shared computer, for example in an internet cafe, and visits protected content belonging to two different clients (let’s call them A and B) within a period of time shorter than the ConnectID session duration (20 minutes) then the ConnectID login prompt will only be displayed for the first client (let’s call that client A). If the user does not uncheck the rememberMeCheckbox during login to client A then the user must remember to log out of client A before leaving the internet cafe to prevent the next user of the shared computer from gaining access to the ConnectID account.

URL parameters Description Required
clientId The unique ID of the client, e.g. no.mediaconnect.test
returnUrl A URL to redirect the user’s browser back to on success (the user will be logged in)
errorUrl A URL to redirect the user’s browser back to if something goes wrong (the user might not be logged in)

URL: register

You can redirect a user’s browser to this URL to let the user search for an existing subscription registered in Connect and tie the ConnectID user to that subscription.

If the user is not already logged in or the credential parameter is specified but the user is logged in with a different credential then the user will first be required to either log in or verify a credential using a one time password.

  • Server: loginServer
  • Relativ path: register
  • Method: GET
URL parameters Description Required
clientId The unique ID of the client, e.g. no.mediaconnect.test
returnUrl A URL to redirect the user’s browser back to on success (the user will be logged in)
errorUrl A URL to redirect the user’s browser back to if something goes wrong (the user might not be logged in)
credential If specified, the credential field will have this value when the GUI is shown but will still be editable by the user (however, the credential field will not be editable if the user already is logged in with this credential or if the user already is logged in and this parameter is not specified)
credentialSubmit If this parameter is set (credentialSubmit=true) will be submit the form with credential given as credential parameter.

URL: resetPassword

You can redirect a user’s browser to this URL to let the user change password.

If the user is not already logged in or the credential parameter is specified but the user is logged in with a different credential then the user will first be required to either log in or verify a credential using a one time password.

  • Server: loginServer
  • Relativ path: resetPassword
  • Method: GET
URL parameters Description Required
clientId The unique ID of the client, e.g. no.mediaconnect.test
returnUrl A URL to redirect the user’s browser back to on success (the user will be logged in)
errorUrl A URL to redirect the user’s browser back to if something goes wrong (the user might not be logged in)
credential If specified, the credential field will have this value when the GUI is shown but will still be editable by the user (however, the credential field will not be editable if the user already is logged in with this credential or if the user already is logged in and this parameter is not specified)
credentialSubmit If this parameter is set (credentialSubmit=true) will be submit the form with credential given as credential parameter.

URL: merge

You can redirect a user’s browser to this URL to let the user merge with other user/credential or just add other e-mail or mobile phone as new login credential. After that user will have possibility to log in with added credential using same password.

User shall be already logged in, but if the user is not already logged in will be prompt to login.

URL parameters Description Required
clientId The unique ID of the client, e.g. no.mediaconnect.test
returnUrl A URL to redirect the user’s browser back to on success (the user will be logged in)
errorUrl A URL to redirect the user’s browser back to if something goes wrong (the user might not be logged in)
abortUrl
A URL to redirect the user’s browser back to if user click on close widget (X) in gui, close component is not visible as default.
heading It is possible to change the default heading in the gui, just with sending this param in url
credentialType If type is not specified then is allowed to put e-mail or mobile, if is set to A - then e-mail is required, if B - mobile is required. Texts on gui will change depends of this credential type.

URL: activateMembership

You can redirect a user’s browser to this URL to let the user search for an existing subscription registered in other partner membership system and tie the ConnectID user to that subscription.

If the user is not already logged in or the credential parameter is specified but the user is logged in with a different credential then the user will first be required to either log in or verify a credential using a one time password.

  • Server: loginServer
  • Relativ path: activateMembership
  • Method: GET
URL parameters Description Required
clientId The unique ID of the client, e.g. no.mediaconnect.test
returnUrl A URL to redirect the user’s browser back to on success (the user will be logged in)
errorUrl A URL to redirect the user’s browser back to if something goes wrong (the user might not be logged in)
credentialType If specified, the credential field will have this value when the GUI is shown but will still be editable by the user (however, the credential field will not be editable if the user already is logged in with this credential or if the user already is logged in and this parameter is not specified)

URL: fulfillment

After placing an order to the client order API or order API, redirect the user to this URL for fulfillment. Depending on the payment method on the order the user will be further redirected to an external payment service.

  • Server: loginServer
  • Relativ path: fulfillment
  • Method: GET
URL parameters Description Required
orderId Order ID returned from the order API. Can be list of orders, but orders need to be from same merchant group id and with same paymentMethod - creditcard.
returnUrl The (absolute) URL the user will be redirected to after the fulfillment is completed.

Return URL parameters:

When the user is redirected a parameter is added to the return URL. The parameter is fulfillmentStatus and will it will have one of the following values:

fulfillmentStatus value Description
success Indicating that the fulfillment was successful.
cancel Some payment methods allow the user to cancel the payment.
error An error occured.
unknown Unknown status, is only when was send with more than one order, and something goes wrong with at least one of them.

Mediaconnect payment SDK

This feature allows our clients to easily enable different payment method options on their websites. We will collect payments on your behalf.
It is a javascript library that our clients can use to facilitate integration with payment intermediaries. It is possible to do payments on the same page(seamless view flow) or use redirect(redirect flow). In order to use this feature please contact Mediaconnect by sending an email to Support at Mediaconnect.

You can see the documentation for older version of McPay here.

McPay servers

There are currently two types of servers in use, namely the mcPayCdnServer and the mcPayApiServer.

mcPayCdnServer
This provides static files e.g. javascript.

mcPayApiServer
This specifies API server, when initializing javascript library it must be provided.

Payment methods

There are several possible payment methods. Payment provider configuration is needed to use these payment methods. Some of the payment providers support recurring payment, see the table below. Note that only some of these payment methods may be available to you, e.g. due to geographic availability, etc.

paymentMethod recurring=true recurring=false flow
creditcardPayex seamless, redirect
vippsRecurring redirect
vippsEcommerce redirect
nexi seamless, redirect

How to use McPay

To use the library you need to include our javascript on your website.
Example:

<script src="[mcPayCdnServer]/lib/v/1/mediaconnectpay.js"></script>

The library is available under mediaconnectpay namespace in javascript. mcPayCdnServer supports different url schemes

  • /lib/v/{dynamicVersion}/mediaconnectpay.js - suggested way of loading the newest version matching requested dynamic version e.g. 1 may return 1.1.2, 1.0 may return 1.0.1, 1.1 may return 1.1.2, 2 may return 2.0.0
  • /lib/public/{version}/mediaconnectpay.js - specific version where version is composed of {major}.{minor}.{patch}, exact matching e.g. 1.0.1, 1.1.2, 2.0.0
  • /lib/beta/mediaconnectpay.js - the newest version under development, should not be used under normal circumstances Newest libary version at this moment is v. 1.1.0.

Please note: Never show the payment script inside an iframe. In general, it may break the payment flow - if not today, then later.

Then you need to initialize it.
Example:

<div id="mediaconnectpay-id"></div>
<script>
    mediaconnectpay.Api.init({
        // see [mcPayApiServer]
        baseUrl: 'https://api-test.mediaconnect.no/capi/mcpay',
        elementId: 'mediaconnectpay-id'
    });
    // ...
</script>

Technical details of init argument object:

Property Type Description
baseUrl string mcPayApiServer url
required
elementId string html element id where library can place generated content
required

Next step is to initiate payment.
Example:

    mediaconnectpay.Api.paymentInit(request, callback, options?);

Technical details of paymentInit request object:

Property Type Description
clientCode string Client code
required
sign string Signed JWT token with payment init parameters
required

Example:

{
  "clientCode": "no.mediaconnect.test",
  "sign": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXltZW50TWV0aG9kIjoiY3JlZGl0Y2FyZFBheWV4IiwicHJvZHVjdFNwZWNDb2RlIjoiVE9UVCIsInByb2R1Y3RTcGVjTm8iOjEsInJlY3VycmluZyI6dHJ1ZSwiY2xpZW50Q29kZSI6Im5vLm1lZGlhY29ubmVjdC50ZXN0IiwiZXh0ZXJuYWxSZWZlcmVuY2UiOiJVVUlELTIwMjItMDMtMDRUMTI6MDA6MDAuMDAwWiIsIm5iZiI6MTY0NjM5NTQ0NywiaWF0IjoxNjQ2Mzk1NDQ3LCJleHAiOjE2NDYzOTkwNDd9._zH3XwyzOzgaaIvsIpw5byAT2It84zrr7t4U65fTmDNoI8AfC8O3f_G99qGv7OkEB1zBJ7Om33XtmB2-9QCwCA"
}

Technical details of paymentInit request sign object before being signed:

Property Type Description
clientCode string Client code
required
paymentMethod string creditcardPayex, vippsRecurring, vippsEcommerce, nexi
required
paymentFlow string seamless, redirect
optional
paymentScope string Scope for vipps payment, space delimited: address birthDate email name phoneNumber
optional
productSpecCode string Coupon code
optional, reuired for recurring
productSpecNo number Coupon number
optional, required for recurring
currency string Currency, if not provided taken from the coupon or partner company default currency
optional
amount number Amount, if not provided taken from the coupon, if coupon is not provided, amount is required
optional, required for non-coupons/multiline orders
vatAmount number Vat amount
optional, should be send for non-coupons/multiline orders
subscriptionStartAmount number Amount that overrides standard start coupon amount
optional
recurring boolean Is this recurring payment
required
description string Passed to payment provider payment window
optional
externalReference string External reference to this payment from client side, unique, one time use only
required
phoneNumber string Phone number
optional
returnUrl string Return url. Url will have additional parameters added about the payment:
mcPayRef - id of the payment, after successful payment use it as mcPayRef to place the order
status - status of the payment, success or failure

optional, required if payment method uses redirect flow
checkoutUrl string Checkout url. Specifies where the checkout will be loaded.

optional, required if payment method is nexi and uses seamless flow

Example:

{
  "paymentMethod": "creditcardPayex",
  "productSpecCode": "TOTT",
  "productSpecNo": 1,
  "recurring": true,
  "clientCode": "no.mediaconnect.test",
  "externalReference": "UUID-2022-03-04T12:00:00.000Z"
}

Technical details of paymentInit callback object:

Property Type Description
onInit function Callback called after payment was initialized, user may fulfill the payment details.
Callback argument #1, paymentInit api response, structure: { mcPayRef: string; }
mcPayRef string, id of the payment
onSuccess function Callback called after payment was successfully completed. Works only during seamless flow, not during redirect flow.
Callback argument #1, paymentInit api response, structure: { mcPayRef: string; }
mcPayRef string, id of the payment, after successful payment use it as mcPayRef to place the order
Callback argument #2, complete response passed from payment provider, available if payment provider make it available otherwise undefined.
onFailure function Callback called after payment failed.
Callback argument #1, paymentInit api response, available if payment was initialized otherwise is undefined, structure: { mcPayRef: string; }
mcPayRef string, id of the payment
Callback argument #2, error response.
Callback argument #3, error response passed from payment provider, available if payment provider make it available otherwise undefined. Callback argument #4, optional, string, failure reason e.g. 'cancel'.
onRedirect function Callback called after payment was initialized with redirect flow. Optional, if onRedirect function provided then you are responsible for handling it, either do redirect in same window or for example in new tab.
Callback argument #1, paymentInit redirect response, structure: { mcPayRef: string; redirectUrl: string; }
mcPayRef string, id of the payment
redirectUrl string, redirect url

Example:

{
    onInit: function (paymentInitResponse) {
        // ...
    },
    onSuccess: function (paymentInitResponse, providerResponse) {
        // ...
    },
    onFailure: function (paymentInitResponse, errorResponse, providerResponse) {
        // ...
    },
    // if onRedirect function provided then you are responsible for handling it
    onRedirect: function (redirectResponse) {
        // ...
    },
}

Technical details of paymentInit options object: This is optional argument, allows you to pass custom options to payment view. After payment is finished base on redirect flow mcPayRef will be returned together with status for payment (success/failure). If payment scope was provided for Vipps payment sub for Vipps user will be also returned.