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)
Step 1: Create the IdP entry
Go to Technical Setup → Identity Provider Configuration
Click on the Add Identity Provider
Enter a name, select Authentication Type: OIDC and Identity Provider Type: MANAGED.
Click Create IdP entry.
Step 2: Enter your connection details
Provide the mandatory information:
Metadata URL: Your application metadata URL
Client ID: Client ID of your Application. In Azure this is the Application ID
Client secret: Client secret of your Application
Identifying Attribute: choose the attribute that identifies your users at sign-in. You will enter this value in the next step and with every user invitation.
Custom template (only if you chose it above): enter your own claim in the format
${CLAIM.attribute_name}, e.g.${CLAIM.employee_id}.Scopes: default is
openid. Add the scope for your attribute if it isn't part ofopenid, e.g.openid email profile.
Matching only works if the scope includes your claim. If you identify users by email, the email scope must be listed.
Copy the Redirect URL shown under Automatically generated metadata and register it in your IdP exactly as provided.
Click Save Metadata.
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.
For any questions, feel free to reach out to support@cofinity-x.com.
Useful Links:
Useful Links:
OSP Registration -
External Registration Callback -
FAQs:
FAQs: