Skip to content

Trading Partner Onboarding (Identity Exchange)

Before your organisation can issue or accept Trading Partner Attribute (TPA) grants, it is highly recommended to establish trust with the remote partner. This is a one-time onboarding handshake typically done out-of-band: both sides export and exchange their Identity Card, verify the card's fingerprint, and import the card to create a TPA Trust.

Because trust must be mutual, the exchange is fully bidirectional:

  • Issuer side: Needs the recipient's orgId to address the grant.
  • Recipient side: Needs the issuer's ML-DSA-44 public signing key to verify incoming grant signatures.

Note: A manual onboarding path using the standalone grant package and public key file is still available as an advanced fallback, but the Identity Card exchange is the recommended, trust-backed path.

The Identity Exchange Handshake

1. Both sides export their Identity Card

Each organisation must generate their own Identity Card:

  1. Navigate to the Policy section and open the My Identity tab.
  2. The page displays your organisation's read-only identity card, including the organisation display name, immutable orgId, and fingerprint details.
  3. Use the Copy JSON or Save to File actions to export the identity-card/v1 package. This JSON payload contains your organisation identifier and your ML-DSA-44 public key.
  4. Note the fingerprint QR shown on the screen. This QR encodes the 32-byte SHA-256 fingerprint of your public key.

Important: The Identity Card never contains private key material. The card does carry a "proof-of-possession" self-signature, but this merely proves the exporter controls the declared public key. It is not an identity proof.

2. Exchange cards out-of-band

Send the exported JSON file to your partner securely. Your partner will send their file to you.

3. Verify the fingerprint (Mandatory)

When you receive a partner's Identity Card, you must not trust it implicitly. The imported package can be easily spoofed if an attacker intercepted the message. You must verify the key fingerprint through a secondary, out-of-band channel.

  1. Get your partner on a phone/video call, or a trusted messaging application.
  2. Have them read the displayed fingerprint out loud, or scan their on-screen Fingerprint QR code with your phone so you can compare the same fingerprint string over a second channel.
  3. The QR code is a reading aid for the fingerprint; it does not contain the full card payload.

4. Import the partner's card

Once you have the card JSON and have confirmed the fingerprint out-of-band:

  1. Navigate to Policy -> TPA Trusts and click New Trust.
  2. Paste the supplied JSON payload into the Paste Identity Card JSON field, or click Load from file to select the card file your partner sent.
  3. The panel parses the card and displays the remote org details and the card's self-signature status.
  4. Confirm the Trust Label (pre-filled from the partner's display name).
  5. Select the Scope Types and Permissions this trust will accept — at least one of each is required. This is the policy envelope incoming grants are validated against.
  6. Tick the box to affirm you verified the fingerprint out-of-band.
  7. Click Create Trust.

Creating the trust this way records a Trading Partner Trust with the partner's pinned identity and signing key and the scope/permission policy you selected, so it is ready to validate incoming grants immediately — there is no separate "configure the trust" step. From this point forward, the trust-backed partner directory lists this partner, so you can select them when issuing Definitions or Grants and the import workflow has a trusted issuer record to resolve against.

Advanced — manual entry: If a partner cannot share a card, click Advanced: enter partner manually in the same panel to hand-type the remote org ID, set the scope types and permissions, and upload their ML-DSA-44 public key directly.

Appending and Key Rotation

If a partner's ML-DSA-44 signing key changes, they simply send you an updated Identity Card. When you import the updated card:

  • The system will append the new public key to the existing trust record.
  • The old key is marked as superseded. This ensures that any in-flight grants previously signed with the old key remain verifiable until they naturally expire or are revoked.
  • Keys are superseded, not silently replaced or dropped.

Next Steps

Once the bidirectional handshake is complete:

  • As an Issuer: When creating a TPA Definition or TPA Grant, use the partner directory picker to select the partner's trusted identity. The system will pre-fill their orgId automatically.
  • As a Recipient: Your trust already carries the scope types and permissions you chose while importing the card, so you can go straight to loading the exported TPA Grant in the TPA Imports tab. The system matches the grant's issuer with the trust you established, verifies the signature against the correctly pinned public key, and checks the grant against the trust policy you configured. (If you need to widen or narrow what you accept later, open the trust and edit its scope types and permissions.)