This guide helps ensure a smooth and secure onboarding experience for new participants, whether you're new to the role or optimizing an existing process. It covers everything from Identity Provider setup to registering partner companies using the API.
📘 Key Concepts
Authentication Type
OIDC (OpenID Connect): A protocol that builds on OAuth 2.0 to provide an identity layer, allowing clients to verify the identity of users and obtain basic profile information.
Identity Provider Type
Managed: This is for setting up an IdP connection that you manage for a third-party organization. It’s useful when you’re administering IdP connections on behalf of other entities (the case for OSP).
Redirect URL
This is the URL where the Identity Provider (IdP) redirects the user after authentication is complete. It typically includes an endpoint where the authentication token or information is sent. This URL is often predefined and auto-generated.
Metadata URL
The Metadata URL is a specific web address containing important information about a system. This URL acts as a digital "fact sheet," helping two systems communicate securely by providing the necessary details for establishing trust and connection.
Identity Provider (IdP)
An Identity Provider (IdP) is the system responsible for verifying user identities when they attempt to log in. Think of it as a digital bouncer that grants or denies access based on whether it recognizes the user. This ensures that only authorized individuals can access specific resources.
IdP Data
IdP Data refers to the information used by the Identity Provider to authenticate users. This includes user details, such as usernames and passwords, as well as rules governing access rights. This data is essential for the IdP to perform its security functions effectively.
Provider ID
The Provider ID is the user ID specific to the Identity Provider being used. This ID varies depending on the IdP:
Azure: A unique sub-ID generated for each user per enterprise application.
Keycloak: A unique user ID.
Identity Provider ID
The Identity Provider ID is a unique ID generated whenever a Managed IdP is registered in the portal. It can be obtained by listing the IDPs in the portal using the following API call:
Beta: GET <https://portal-backend.beta.cofinity-x.com/api/administration/identityprovider/owncompany/identityproviders>
PROD: GET <https://portal-backend.svc.cofinity-x.com/api/administration/identityprovider/owncompany/identityproviders>
Authorization: Bearer <your token>
You can find your token in your Account Page in Portal
Onboarding a new Company
Confirm Access to the OSP Role
To begin, ensure your company is registered as an OSP. Navigate to "Your Company" and you can see all Roles currently assigned to your company
Contact Cofinity-X support if you want to become an OSP.
Create Technical User for API Authorization
OSPs need to create a technical user, which involves generating and securing a Client ID and Client Secret specifically for API interactions. This technical user is crucial for enabling subsequent API-based actions in the onboarding process.
Go to Technical Setup → Technical User Management
Create a new user and assign the role:
Registration External⚠️ This role confirms your OSP permissions. If you do not see this role, that means the OSP role is not currently enabled for you.
Save the generated Client ID and Client Secret — you’ll use these for authentication when making onboarding API calls.
Configure Your Identity Provider (IdP)
OSPs set up the Identity Provider (IdP) using OpenID Connect (OIDC). This involves configuring Metadata URLs, Client IDs, and Client Secrets essential for authenticating identities managed by the OSP.
Go to Technical Setup → Identity Provider Configuration → Add Identity Provider
Select:
Authentication Type: OIDC
Identity Provider Type: Managed
After Creating the IDP entry, you need to configure the connection details to your company IdP.
As the OSP, you now need to come with your own Open ID instance (keycloak, Azure, Google …) and with it your Metadata URL, Client ID and Client Secret from your Open ID Instance. The Client ID here corresponds to the Application ID (if using Azure) or will be called Client ID or ID of Client in keycloak for example or in your specific Open ID instance.
Provide:
Your Metadata URL ending in
/.well-known/openid-configurationYour Client ID and Client Secret from your OpenID instance (Azure, Keycloak, etc.)
Register the redirect URL in your Open ID instance (without the wildcard)
Once saved, your IdP is ready to use for onboarding.
Collect Information from Customers
The OSP gathers necessary details from customers, such as company-specific data required for the registration process. This step ensures that all relevant information is collected before initiating the registration invites.
Send Registration Invite via API
Using the configured IdP setup, OSPs send out registration invites. This step involves registering the partner company by providing detailed information, including the collected specific company data. This is a critical step where the OSP formalizes the inclusion of the partner company into the system.
Mandatory Fields
When onboarding a new participant, the following fields must be completed:
Company Name
External ID: A self-generated UUID (format UUID) unique to each OSP, used to identify invitations and other API calls. Must be between 6 and 36 characters and unique for each OSP.
Country: Must be a valid 2-digit Alpha2Code country code.
City
Street
uniqueID Type
uniqueID Value
Provider ID: Unique user identifier in the IdP (e.g. sub-ID in Azure)
Identity Provider ID: Internal ID in Cofinity-X portal; can be found via Developer Tools or API
firstName: Must be valid; two names allowed, "-" allowed; special characters like "#", "?", "!", etc., are not allowed.
lastName: Must be valid; two names allowed, "-" allowed; special characters like "#", "?", "!", etc., are not allowed.
email: Must be a valid email address.
Additional Requirements:
BPN field: Must be either empty (null) or filled with exactly 16 digits starting with "BPNL" if available.
CompanyRole: Only supported roles are allowed. Ensure the correct role is chosen.
ACTIVE_PARTICIPANT,APP_PROVIDER, orSERVICE_PROVIDER
In your API tool (e.g. Postman):
Auth Type: OAuth 2.0 → Client Credentials
Token URL:
Beta:
https://centralidp.beta.cofinity-x.com/auth/realms/CX-Central/protocol/openid-connect/tokenProd:
https://centralidp.svc.cofinity-x.com/auth/realms/CX-Central/protocol/openid-connect/token
Use the Client ID and Secret from your technical user created from Cofinity-X Portal.
Endpoint to send registration payload:
Beta:
https://portal-backend.beta.cofinity-x.com/api/administration/registration/Network/partnerRegistrationProd:
https://portal-backend.svc.cofinity-x.com/api/administration/registration/Network/partnerRegistration
Sample Payload:
{
"name": "Alecs IceCreamInc",
"city": "Munich",
"streetName": "Petuelring",
"countryAlpha2Code": "DE",
"shortName": "Alecs",
"region": "",
"streetAdditional": "",
"streetNumber": "130",
"zipCode": "80809",
"uniqueIds": [
{
"type": "VAT_ID",
"value": "DE123456789"
}
],
"externalId": "853da13b-7c20-4ec7-a236-60b3c48518a7",
"userDetails": [
{
"identityProviderId": "1662a052-122d-4d20-a23a-d402d700000",
"providerId": "1e2juT9tQhHAcFq_bcW3jEtpRh6ACgUt9rIGO-00000",
"username": "",
"firstName": "Hans",
"lastName": "Beck",
"email": "hans.Beck@cofinity-x.com"
}
],
"companyRoles": [
"ACTIVE_PARTICIPANT"
]
}
📩 A 200 OK response means the invitation was sent successfully.
End of OSP Onboarding Role
Once this is done, an email is then sent to the Admin user you’re inviting. The Admin will receive an email that looks like the screenshot below and can then proceed with viewing and accepting the consent agreement.
Once the registration invites are sent, the OSP's role in the onboarding process for that partner is concluded. This marks the transition to the next phase handled directly by Cofinity-X.
Additional Helpful Resources
Configuring Azure as an example to retrieve necessary details.
Create New Enterprise Application.
Log in to your Microsoft Azure account.
Navigate to Enterprise Applications.
Create New Application
Register the Application.
From the Homepage, navigate to App Registrations.
Register your Application
In your application, navigate to ‘Overview’. The application ID is your Client ID needed in the above step of configuring the connection details to your company IdP
In your application, navigate to ‘Manage’ >> ‘Certificates & Secrets’ and create a new secret. This will be your Client Secret in the above step of configuring the connection details to your company IdP.
In your application, navigate to ‘Overview’. Locate the Endpoints option and you will find a list of endpoints. Your Metadata URL is the endpoint that ends in ‘/.well-known/openid-configuration’
Register the redirect URL in your Open ID instance
Copy and paste the redirect URL from Portal in the Authentication
Retrieving the Provider ID from Cofinity-X:
Here are the steps you can follow to retrieve your Provider ID:
First, if you haven't already, create a managed IDP in the Cofinity-X Portal. Please avoid sending out the registration invite until you have obtained your provider ID.
Logout from your company and log in to the newly created managed IDP in the Cofinity-X Portal.
Upon logging in, you may be prompted to log in to Azure. After successful login, you'll see a screen that displays the username, which you can use as the "ProviderId" in the invitation payload.
Retrieving the Identity Provider ID from Portal (Developer Tools)
Navigate to Technical Setup >> Identity Provider Configuration in the Cofinity-X Portal.
Access the Developer Tools: Right-click the page, select Inspect, and go to the Network tab.
Search for
identityprovidersin the Network tab's filter bar.Click the
identityprovidersrequest that matches with the IDP, go to the Response section, and locate the ID matching your IDP alias.Note the corresponding Identity Provider ID for your IDP alias.
Useful Links:
Useful Links:
OSP Registration -
External Registration Callback -