Self-Service (Easy Onboarding)
Introduction
The CrefoTrust self-service gives a Verifier a hosted flow for identity verification. The Verifier does not need to create orders through the API and does not need an API key for this path. CrefoTrust creates the order in the background after the user logs in or registers.
For each case the Verifier creates one link and gives it to the user. The user completes the identification, CrefoTrust sends the result to the Verifier’s webhook, and the browser is redirected to the Verifier’s success or failure page.
Environments
| Environment | Self-service base URL |
|---|---|
| Test / integration | https://self-service-cust.crefotrust.de |
| Production | https://self-service.crefotrust.de |
The test environment uses the test data described in Testing. Do not use real personal data in tests.
Creating the link
The link uses the usecase name provided by CrefoTrust and a reference:
{SELF_SERVICE_BASE}/?usecase={useCaseName}&verifierRef={reference}
Optional company context:
{SELF_SERVICE_BASE}/?usecase={useCaseName}&verifierRef={reference}&crefoId={crefoId}
Example:
https://self-service-cust.crefotrust.de/?usecase=some_use_case&verifierRef=CASE-2026-000123&crefoId=2011234567
Warning: the entry URL is user-controlled. The user can change, remove, or replace
crefoIdand any other query parameter before opening the link.crefoIdonly preselects a company; it does not bind the identification to that company and is not proof that the verified company is the intended one. The receiving webhook must check the submitted company data against the originally targeted company and handle deviations; see Webhook.
Important: the query parameter is
usecase(lowercase). The olderuseCasespelling is not read by the self-service entry.
Reference formats
The input parameter is always verifierRef.
A plain value:
?usecase=some_use_case&verifierRef=CASE-2026-000123
is stored as:
{ "referenceId": "CASE-2026-000123" }
A URL-encoded JSON object:
?usecase=some_use_case&verifierRef=%7B%22customerRef%22%3A%22CASE-2026-000123%22%7D
is stored unchanged:
{ "customerRef": "CASE-2026-000123" }
customerRef is not a top-level query parameter. It is only an example key
inside the JSON value, or the name of a redirect parameter configured by
CrefoTrust.
Rules:
- Use a unique reference per case.
- URL-encode the value; JSON must be encoded as a whole.
- Do not use personal data, secrets, or credentials as the reference. It is visible to the user, in browser history, and in logs.
- A reference value is a map of strings; CrefoTrust supports up to 10 keys and 1024 characters per value. Keep the practical URL length short.
crefoIdis optional and only applies to company cases.
Flow
- The user opens the link.
- The user logs in to the CrefoTrust self-service or registers.
- CrefoTrust creates the order after authentication.
- The user completes the identification.
- CrefoTrust calls the Verifier webhook.
- The browser is redirected to the success or failure URL.
The order is not created when the link is opened; authentication is required first. This matters when testing: a freshly opened link that only shows the login page has not created an order yet.
Webhook
CrefoTrust calls:
POST {YOUR_WEBHOOK}/{orderId}
The payload contains the released credentials and the reference under
meta.verifierRef:
{
"orderId": "6d1f5f0e-8c4f-4a1f-9d6e-0f3f5f7c9a11",
"meta": {
"verifier": "<verifierId>",
"verifierRef": {
"referenceId": "CASE-2026-000123"
}
}
}
WARNING: The webhook meta object will change in a future release. For
now, only rely on the top-level orderId and meta.verifierRef. Do not build
on the placement or shape of the other meta fields; we will announce the
migration before the change is deployed.
Requirements:
- Respond quickly with a
2xxstatus. - Process idempotently, at minimum by
orderId. - Validate the caller using the agreed custom header and/or a network allowlist. The payload is not signed.
- Treat the payload as personal/confidential data.
- Verify the company against the case: the
crefoIdin the entry URL is user-controlled, so do not assume that the submitted company is the one that was targeted. Compare the company data in the payload (org.crefoId,org.legalName, and address) with the company stored for the case. Define how to handle deviations — for example reject the result, flag it for manual review, or start a new case — and never approve automatically on a mismatch. Treat missing company data as a deviation as well. - If the webhook fails, the user is redirected to the failure URL; the webhook is not automatically retried.
Success and failure URLs
CrefoTrust configures the success and failure URLs in the use case. The browser
return includes orderId and the reference parameters configured in
redirect.additionalQueryParams.
For the plain format, map the scalar field:
{
"success": "https://customer.example/cases/success",
"failure": "https://customer.example/cases/failure",
"additionalQueryParams": [
{ "name": "orderId", "field": "id", "required": false },
{
"name": "verifierRef",
"field": "options.verifierRef.referenceId",
"required": false
}
]
}
For the JSON format, map the specific key:
{
"name": "customerRef",
"field": "options.verifierRef.customerRef",
"required": false
}
Example return URL:
https://customer.example/cases/success?verifierRef=CASE-2026-000123&orderId=6d1f5f0e-8c4f-4a1f-9d6e-0f3f5f7c9a11
Important:
- The failure URL is not a guaranteed callback. On abort, identification errors, timeouts, or other terminal failures, the user may never reach it.
- Do not treat
orderIdor the reference from the URL as proof of authorization. Enforce authorization in your own application. - The webhook is authoritative for reconciliation.
- Set a restrictive
Referrer-Policyon the success/failure pages; the reference is in the URL.
Testing
Use the test environment and the static or prepared test data described in
Testing. The fixed test data is available at
/static_mocks.json.
Test checklist:
- Open the link with a unique plain
verifierRef. - Log in or register with a test user.
- Confirm the order is created after authentication.
- Complete the identification with the agreed test data.
- Verify the webhook
meta.verifierRefmatches the reference. - Verify the success URL contains the mapped reference and
orderId. - Verify the webhook custom header and idempotency.
- Verify the failure/abort behavior when the failure URL is reached.
- Do not use personal/secret data as the reference.
Security
- The reference is user-controlled input and must not be used as an authorization credential.
- The entry URL is user-controlled.
crefoIdandverifierRefcan be changed or removed by the user and are not binding; verify the webhook result against your stored case data. - Use an opaque reference; do not put names, email addresses, tax IDs, or secrets in the URL.
- Keep the webhook protected with the agreed custom header and/or network allowlist.
- The webhook payload is not signed.
- Treat the reference as data that may appear in browser history, access logs,
proxy logs, and
Refererheaders.