Skip to main content

Company Registration

This chapter describes how a new Company entity is created in the DEUSS Core platform. Company registration stores the canonical company data in the Core relational database and schedules the asynchronous on-chain provisioning of the company's identity, wallet, and managers.

The action can be initiated by an integrated external Broker through the partner API or by a DEUSS Backoffice Administrator through the admin flow.

Business Rules​

  1. Unique company identity: The platform must not already contain a company with the same businessId, vatNumber, or legalEntityId as the submitted company.
  2. Partner authorization: In the partner flow, the caller must be authenticated via mTLS and the API Gateway must provide the X-Partner-Id and X-Partner-Role headers.
  3. Broker-only partner creation: The partner flow is allowed only when X-Partner-Role equals BROKER.
  4. Admin authorization: In the admin flow, the acting Backoffice user must be logged in and their JWT token must contain the REGISTRY_MANAGER role.
  5. Broker assignment: In the partner flow, broker_id is derived from X-Partner-Id; any broker_id submitted in the request payload is ignored. In the admin flow, broker_id must be provided explicitly in the payload.
  6. Auditability: Every company creation attempt is recorded in audit logs with the identity of the caller.
  7. Asynchronous blockchain provisioning: The API returns after the off-chain entity and chain operation records are created. It does not wait for blockchain confirmation.

Business Flow​

  1. Registration Initiation:

    • A company can be registered either by an integrated Broker Partner System or by a DEUSS Backoffice Administrator.
    • In the partner flow, the broker calls the Registry Service through the partner-facing API after successful mTLS authentication. The API Gateway passes the authenticated partner context to the Registry Service through X-Partner-Id and X-Partner-Role.
    • In the admin flow, a Backoffice user creates the company through an authenticated admin request. The user's JWT must prove that they are allowed to manage registry data.

  2. Authorization and Broker Assignment:

    • The partner flow is restricted to callers with the BROKER role. The Registry Service derives the company's broker_id from X-Partner-Id, so the broker relationship is based on the authenticated integration context rather than on client-submitted data.
    • The admin flow is restricted to users with the REGISTRY_MANAGER role. In this case, the administrator explicitly selects or submits the broker_id that should be assigned to the new company.
    • This distinction prevents an external partner from creating companies under another broker while still allowing controlled administrative onboarding from the Backoffice.

  3. Off-Chain Company Creation:

    • The Registry Service validates the submitted company details before persisting the company. The company must not duplicate an existing legal identity, business identifier, or VAT number.
    • After validation, the Company entity is stored in the Core relational database. The creation is recorded as an audit event, including the identity and context of the caller.
    • The service also creates records in chain_operations for the on-chain provisioning work that must happen after the relational entity exists.
    • The API response is returned immediately after the off-chain work is complete. It includes the created Company entity and the chain operation IDs, but it does not wait for blockchain finality.

  4. Asynchronous On-Chain Provisioning:

    • Because DEUSS uses DLT infrastructure, company creation continues in the background after the synchronous API call succeeds.
    • JobRunnr picks up the pending operation from chain_operations and submits the relevant smart contract transaction to provision the company's on-chain identity, wallet, and manager configuration.
    • Once the transaction is submitted, the operation record is updated with the tx_hash. A polling process then follows the transaction until the final on-chain result is known.
    • When the transaction is confirmed successfully, the operation is marked as COMPLETED. At that point, the company has both an off-chain Core representation and the required on-chain infrastructure.

  5. Failure Handling:

    • If credentials are missing or invalid, the request is rejected as unauthorized. If the caller is authenticated but lacks the required role, the request is rejected as forbidden.
    • In the admin flow, a missing broker_id prevents the company from being created, because the system cannot determine which broker should own the relationship.
    • If the submitted legal identity already exists, the Registry Service rejects the request as a duplicate instead of creating a second company record.
    • Blockchain failures are handled asynchronously. If the RPC endpoint is temporarily unavailable, JobRunnr retries the operation. If retries are exhausted or the transaction reverts on-chain, the chain operation is marked as FAILED and requires administrative attention.

Process Guarantees​

The company registration process guarantees that the off-chain Company entity is created only after the caller is authorized and the submitted identifiers pass uniqueness validation. It also guarantees that the broker assignment is derived from the trusted source for the given flow: authenticated partner headers for broker integrations, or an explicit Backoffice payload for administrative onboarding.

Successful registration creates an auditable Core record and schedules the required blockchain provisioning without blocking the user-facing API on transaction confirmation. This keeps company creation responsive while preserving traceability of the later on-chain work through chain_operations.

Sequence Diagram​