FAQs

Q1. Is this service multi-tenant, and how is a tenant selected?

Yes. Every business route requires an instanceId (query param). The service resolves and caches the instance per request and rejects operations on INACTIVE instances with INSTANCE_INACTIVE (403).

Q2. How does order validation work?

POST /v1/accounts/:accountId/validate runs four gates: active contract → active budget → budget headroom (orderAmount + spent ≤ amount) → credit limit (PURCHASE_ORDER only). It returns 200 { valid: true } or 422/400 with a reason + errorCode. See §4.

Q3. How are budgets debited and is it safe to retry?

Post a DEBIT (or CREDIT) to POST /v1/budget-transactions. Both are idempotent by orderId: a repeated DEBIT with the same amount returns the existing record; a different amount yields BUDGET_DEBIT_AMOUNT_MISMATCH (409); a CREDIT without a prior DEBIT yields BUDGET_CREDIT_WITHOUT_DEBIT (422). Concurrent duplicate-key races are also treated idempotently.

Q4. What is the difference between self-registration and admin invite?

POST /v1/accounts/register with adminInvite absent/false is public and creates a PENDING account + ACTIVE user. With adminInvite=true it requires account:create:account, creates a PENDING account + NOT_ACTIVATED user, and sends an invite email. POST /v1/admin/accounts/register is an authenticated admin-only variant (hidden from Swagger).

Q5. How is authorization enforced?

Each route declares a required privilege (account:<action>:<resource>) that is checked against the platform auth service. Denial → AUTH_INSUFFICIENT_PERMISSIONS (403). There is no role model inside the service; authority comes from platform privileges in the JWT. (Exception: GET /v1/account-types has no privilege check — see §3.)

Q6. What events does the service emit, and can I rely on them?

It publishes accountservice/<domain>/<action> events to EventBridge (source account-service). Publishing is best-effort and non-blocking (failures are logged, not surfaced) and is disabled when STAGE=test. There are no in-repo consumers.

Q7. Can a tenant customize validation or business logic?

Yes for validation — per-domain custom validators are loaded from pluginConfig and take precedence over defaults (§10.1). The lifecycle pre/post-handler extension framework exists but is not wired (§10.2).

Q8. Where’s the full list of error codes / endpoints / privileges?

Endpoints and their required privileges are summarized in §3 and available live in Swagger UI at {base}/documentation. Error codes are catalogued by category in §7.

Q9. Can I run it without MongoDB or Redis?

Yes — set ACCOUNT_USE_INMEMORY=true for an in-memory Mongo adapter (Redis is stubbed). Redis is otherwise gated by CACHE_ENABLED.

Revision History
2026-08-05 | AN – Created the page and added the content.