Credential vault & rotation

Outcome

Trading-partner credentials are stored encrypted in the vault, never displayed in the UI, rotated cleanly without an outage window, and have a clear audit trail of who rotated what and when.

Prerequisites

Scope	What it lets you do
edi.partner.read	View last-rotated dates
edi.partner.credentials.write	Set / rotate credentials

A partner record (see 2.1 — Onboard a new partner).

How the vault works

• The UI submits secrets to the gateway, which writes them to the vault.
• The vault returns only metadata to the UI: credentials_set_at, credentials_last_rotated_at, credentials_set_by, secret_names.
• Outbound transactions read the secret on demand inside the gateway.
• A vault entry is deleted only by an explicit rotate or by deleting the partner record.

Steps to set credentials for the first time

1. Open the partner detail at /trading-partners/:id → Credentials tab. The tab shows current state — usually Credentials not set for a new partner.

2. Click Set credentials. The dialog adapts to the partner's connection type:

   Type	Fields
   SFTP	Username + (password OR private key).
   AS2	Our certificate, partner certificate, optional partner CA chain.
   REAL_TIME	Bearer token / username+password / client certificate.

   The dialog uses input type password for all secret fields; the browser does not autofill them. The value is submitted as soon as you click Save and is never reflected back.

3. Save. The dialog closes; the tab now shows Credentials set on YYYY-MM-DD by <user> and a list of which secret names are set.

4. Run Test connection (see 2.5 — Probe & test connection).

Steps to rotate credentials

Rotation is the same flow as initial set; the platform replaces the secret atomically:

1. Click Rotate credentials on the Credentials tab.

2. Submit the new secret. The vault writes the new value; outbound traffic uses the new value on the next request.

3. The Credentials tab updates — credentials_last_rotated_at is the new timestamp; credentials_set_by is your user.

4. Run Test connection to confirm the new secret is accepted.

There is no transitional window where the partner has neither old nor new credential in place. The rotate is a single transactional write at the vault layer.

Coordinating rotation with the partner

Most partner side-rotations are scheduled — you know about them in advance. The recommended sequence:

If the partner cannot expose the new secret until cutover, schedule the rotate inside the partner's first-acceptance window for the new secret. Probe immediately to confirm.

Steps to delete credentials

Rare; only when retiring a partner record:

1. Confirm the partner has no active routing rules. A delete with active routes leaves orphan submissions failing.

2. Disable the partner under Overview → Active toggle.

3. Click Clear credentials on the Credentials tab. The vault entry is deleted; the partner record stays for audit purposes.

Audit trail

Every rotation produces an audit row:

Field	Content
When	Server timestamp.
Who	The user.
Action	partner.credentials.set / partner.credentials.rotate / partner.credentials.clear.
Partner	Partner ID + display name.
Secret names	Which keys were set / rotated; never the secret values.

Visible at the platform-side audit log; tenant-side staff can see the rotation events on the Credentials tab's history strip.

Validation

Check	Expected
Set credentials returns 200	Yes; tab updates with new metadata.
Probe succeeds with new credentials	Yes.
Audit log carries the rotate row	Yes.
Old credential is unusable for outbound	Yes — no fallback to prior value.

Troubleshooting

Symptom	Cause	Fix
Save returns 409 Conflict	Concurrent rotate from another admin	Reload; re-confirm intent; the latest write wins (the audit log records both attempts).
Outbound traffic still fails after rotate	Partner has not yet promoted the new secret on their side	Coordinate with partner; do not roll back — the audit trail is cleaner with one well-known issue than two rotations.
Probe succeeds but inbound poll fails with auth error	Inbound credential is separate (SFTP partners sometimes provision two logins); only one was rotated	Rotate the inbound credential too.
Cannot clear credentials: "active routing rule references partner"	Routing rule still picks this partner	Update the routing rule first, then clear.

Next

2.4 — Capabilities