Merchant Users And Finance Assistant Keys

This page defines the operational contract between merchant records, merchant auth users, and Finance Assistant key usage.

Canonical Lifecycle

1. Merchant profile is created in Merchant API (/api/merchants).
2. Merchant auth user is provisioned/repaired in Auth API (/admin/merchant-users/provision).
3. Merchant receives/retains Finance Assistant API key in auth store.
4. Admin can run full reconciliation (/admin/merchant-users/sync) as backfill.

Data Responsibilities

• merchants.json:
  • merchant profile data and merchant key (profiles[merchantId])
• merchant-router.json:
  • environment/domain routing keyed by merchant ID
• auth-credentials.json:
  • merchant user login/API identity keyed by username
  • merchant linkage through merchantId + metadata.merchantId
  • merchant Finance Assistant key (apiKey)

Finance Assistant API Key Role

• Used for Finance Assistant workflows:
  • enquiry submission
  • lender start-finance-application calls
• Not required for partner quote maths path.
• Missing key behavior:
  • quote endpoint may still return valid products
  • Finance Assistant side-effects can fail (especially without proxy fallback key mapping)

Merchant ID Change Rules

Merchant ID updates must be treated as migrations:

• Preflight checks must pass before write:
  • old ID exists
  • new ID does not exist
  • env config files are readable
  • no ID conflicts in env configs
• Migration must update all required stores:
  • merchants.json keys
  • merchant-router.json keys
  • environment merchant config ID fields
  • auth merchant user ID mapping
• If required migration step fails, rollback should be attempted and surfaced as an explicit error.

Audit / Merchant History Requirements

Every merchant profile-affecting action must emit a history event.

Required fields:

• actor_type: admin_user or automation
• actor_id and actor_name
• change_source
• correlation_id (when available)
• details with meaningful change context

Applies to:

• manual admin profile edits
• merchant ID changes
• environment switches
• Stripe link/unlink actions
• automated sync/ingestion jobs that alter merchant data

Reconciliation Checklist

Use this when investigating onboarding or drift:

• merchant exists in Merchant API
• merchant user exists in Auth API with role merchant
• merchant user has merchantId and metadata.merchantId
• merchant user has apiKey
• no conflicting username mapping
• merchant history contains events for recent profile mutations