Download OpenAPI specification:Download
ConnectID is a solution for user authentication, authorization and payment for web pages and apps. ConnectID is made by Mediaconnect AS.
The main parties using ConnectID are:
The stages in API lifecycle are listed in chronological order below:
You can read more about the API-life cycle on our knowlegde base.
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.
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:
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.
There are currently two types of servers in use, namely the loginServer and the apiServer.
loginServer
apiServer
The minimum configuration to create a new client in ConnectID are listed below:
Its very important that client logo is in a good quality. Best if has transparency when needed. Acceptable formats are:
Dimension of the logo image should be at least (for best view):
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.
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.
We are supporting two types of Authorization grant types:
The authorization token is provided by the authorization endpoint and is used with the token endpoint to get an access token.
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.
The access token is provided by the token endpoint and is required in order to access the ConnectID APIs.
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:
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. |
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:
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.
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. |
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. |
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.
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. | ✔ |
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) | ✔ |
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.
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. |
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.
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. |
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. |
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.
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) |
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.
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. |
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.
mcPayApiServer
This specifies API server, when initializing javascript library it must be provided.
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 |
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
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; }
|
||||
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; }
|
||||
onFailure | function | Callback called after payment failed. Callback argument #1, paymentInit api response, available if payment was initialized otherwise is undefined, structure: { mcPayRef: string; }
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; }
|
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.