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.

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

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.

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

• How to use our Connect events and ConnectID events
• How to send a order by using our APIs
• How we support the use of Google analytics

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

• Production: https://connectid.no/user/ or https://connectid.se/user/
• Test: https://api-test.mediaconnect.no/login/ (Note the /login/ path at the end)

apiServer

• Production: https://api.mediaconnect.no/capi/
• Test: https://api-test.mediaconnect.no/capi/

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

Client Logo

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; }

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.

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:

• Production: https://api.mediaconnect.no/capi/
• Test: https://api-test.mediaconnect.no/capi/

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

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:

• Production: https://api.mediaconnect.no/capi/
• Test: https://api-test.mediaconnect.no/capi/

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.

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

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.

• Server: loginServer
• Relativ path: login
• Method: GET

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

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.

• Server: loginServer
• Relativ path: logout
• Method: GET

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

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

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.

• Server: loginServer
• Relativ path: merge
• Method: GET

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

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

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:

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.

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

mcPayCdnServer
This provides static files e.g. javascript.

• Production: https://api.mediaconnect.no/mcpay
• Test: https://api-test.mediaconnect.no/mcpay

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

• Production: https://api.mediaconnect.no/capi/mcpay
• Test: https://api-test.mediaconnect.no/capi/mcpay

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.

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:

Next step is to initiate payment.
Example:

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

Technical details of paymentInit request object:

Example:

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

Technical details of paymentInit request sign object before being signed:

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:

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.