Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintfax.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

You are adding fax to your product. Your customers will send faxes through your platform, and you need to decide how to structure the integration so that each customer’s traffic, billing, and compliance stay separate. mintfax’s workspace model gives you two options: one workspace per customer, or a shared workspace where you handle tenant isolation yourself. This guide covers both patterns, the tradeoffs, and the operational details that matter when you go live.

​
Workspace-per-customer

Create a separate mintfax workspace for each of your customers. Every workspace gets its own API keys, credit balance, webhook configuration, retention settings, and (optionally) its own BAA. When to use this pattern:
  • Your customers have different compliance requirements. A healthcare customer needs a BAA and zero-footprint retention; a logistics customer does not.
  • You want billing isolation. Each workspace carries its own prepaid balance, so one customer’s spending never affects another’s.
  • You need per-customer audit trails. Audit logs are scoped per workspace, which simplifies compliance reporting.
  • You are building a platform where each customer might eventually want direct access to their own mintfax dashboard.
How it works in practice:
  1. When a customer signs up for fax on your platform, your backend creates a mintfax workspace via the API.
  2. Your backend stores the workspace’s API key in your secrets manager, mapped to the customer’s tenant ID.
  3. When that customer sends a fax through your product, your backend authenticates to mintfax using that customer’s workspace key.
  4. Webhooks arrive at your endpoint with the workspace context, so you know which customer the event belongs to.
Each workspace has separate sandbox and live environments. Use the sandbox environment for integration testing per customer before switching to live keys.

​
Shared workspace

Use a single mintfax workspace for all of your customers. You manage tenant isolation in your own application layer. When to use this pattern:
  • All customers share the same compliance posture and retention settings.
  • You want to manage billing yourself rather than topping up individual workspace balances.
  • You have a small number of customers or are early-stage and want the simplest integration.
How it works in practice:
  1. Your backend holds one set of mintfax API keys (sandbox and live).
  2. When any customer sends a fax, your backend submits it using the shared key.
  3. You use the per-fax webhook_url parameter (covered below) to route delivery notifications to customer-specific handlers, or you fan out from a single webhook endpoint using fax metadata you store on your side.
  4. You track credit consumption per customer in your own database using fax records and webhook events.
The tradeoff is clear: simpler setup, but you own the isolation. If one customer needs a BAA or different retention rules, you need a separate workspace for that customer.

​
Credential management

Regardless of which pattern you choose, one rule is absolute: your backend holds the API keys. Never expose mintfax credentials to your end users’ browsers, mobile apps, or client-side code. Your architecture should look like this: 
End user -> Your frontend -> Your backend -> mintfax API
Your backend authenticates to mintfax, submits the fax, and returns the result to your frontend. The API key never leaves your server. Store keys in environment variables or a secrets manager. If you use the workspace-per-customer pattern, your secrets store maps each tenant ID to its mintfax API key. Rotate keys through the dashboard - both the old and new keys work simultaneously during the transition, so you can update your secrets store without downtime.

​
Webhook routing

When a fax is delivered or fails, mintfax sends a webhook event. In a multi-tenant setup, you need each event to reach the right customer’s processing logic.

​
Option 1: Per-fax webhook URL

Pass webhook_url on each POST /v1/fax request to override the workspace-level webhook endpoint. This lets you route callbacks to a customer-specific URL or a URL that encodes the tenant context. 
curl -X POST https://api.mintfax.com/v1/fax \
  -H "Authorization: Bearer fx_live_abc123..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "to=+12125551234" \
  -F "file=@document.pdf" \
  -F "webhook_url=https://yourapp.com/webhooks/mintfax/tenant/cust_8xk2m"
Your webhook handler parses the tenant ID from the URL path and processes the event in that customer’s context. This approach works well with the shared workspace pattern - you get per-customer routing without managing multiple workspaces.

​
Option 2: Fan-out from a single endpoint

Configure one webhook endpoint on the workspace and fan out internally. When you submit a fax, store the fax ID alongside the customer’s tenant ID in your database. When the webhook arrives, look up the fax ID to determine which customer it belongs to, then route accordingly. 
{
  "event_id": "evt_abc123def456",
  "event": "fax.delivered",
  "data": {
    "id": "9c1a2b3d-4e5f-6789-abcd-ef0123456789",
    "status": "delivered"
  }
}
Your handler receives this, looks up fax ID 9c1a2b3d-... in your database, finds it belongs to cust_8xk2m, and processes accordingly.

​
Which to choose

Per-fax webhook URLs are simpler if you want stateless routing - the tenant context is in the URL itself. Fan-out is better if you want a single ingestion point with centralized signature verification and logging. Both approaches work with either workspace pattern. Verify every webhook payload using the HMAC-SHA256 signature. See Webhook signing for verification recipes in multiple languages.

​
Billing pass-through

If you charge your customers for faxing, you need to track what each customer consumes. Workspace-per-customer: Each workspace has its own balance. Query GET /v1/account/balance with the customer’s workspace key to get their credit state. Subscribe to balance.low webhook events to alert your system (or the customer) when credits run low. You can either let customers fund their own workspaces or top up programmatically from your platform’s billing system. Shared workspace: You own the accounting. When you submit a fax, record the fax ID and customer in your database. When you receive a fax.delivered or fax.failed webhook, update the customer’s usage record. Delivered faxes consume credits (per page); failed faxes release the hold and cost nothing. The credit lifecycle is hold-capture-release:
  1. On submission, mintfax places a hold for the estimated cost.
  2. On delivery, the hold is captured as a permanent charge.
  3. On failure, the hold is released back to the available balance.
See Credits for the full lifecycle and balance queries.

​
Idempotency in multi-tenant systems

Idempotency keys are scoped per environment, not globally. If two customers in different workspaces happen to use the same idempotency key, there is no collision - each workspace is independent. In a shared workspace, keys are unique within that workspace’s environment, so make sure you generate unique keys per fax submission regardless of which customer triggered it. Keys expire after 24 hours. See Idempotency for the full behavior.

​
Compliance considerations

If any of your customers handle protected health information, you need workspace-level compliance controls. BAA: mintfax signs a BAA per workspace at no extra cost. If you use the workspace-per-customer pattern, you can sign a BAA for the workspaces that need it and skip it for those that do not. If you use a shared workspace and any customer needs a BAA, you sign one for the shared workspace. Retention: Each workspace can be configured for standard retention (configurable window, default 90 days) or zero-footprint mode (data deleted after the fax reaches a terminal state). Healthcare customers typically want zero-footprint mode. In the workspace-per-customer pattern, you set the retention mode per workspace. In a shared workspace, all customers share the same retention policy. The workspace-per-customer pattern is strongly recommended for healthcare SaaS. It gives you per-customer BAAs, per-customer retention policies, and per-customer audit logs - exactly what you need for compliance reporting. See HIPAA compliance for the full compliance boundary and BAA signing process.

​
Testing multi-tenant flows

Use sandbox environments to test each tenant’s flow before going live.
  1. Create a sandbox workspace (or use the sandbox environment of an existing workspace).
  2. Configure webhook endpoints and test with the sandbox magic numbers. +15005550001 simulates successful delivery; other magic numbers simulate failures.
  3. Verify that webhooks arrive at the correct per-tenant URL or that your fan-out logic routes to the right customer.
  4. Test the billing flow: submit faxes, confirm holds are placed, and verify that delivery events trigger the right credit accounting in your system.
  5. When everything works, switch to live keys. Sandbox and live are fully isolated - no data, settings, or history carries over.

​
What to do next

  • Authentication for API key types, rotation, and security practices.
  • Webhooks for event types, payload format, and delivery behavior.
  • Go live for the checklist to activate your live environment and start sending real faxes.
  • HIPAA compliance for BAA signing, retention controls, and the compliance boundary.