Users & Magic Links

Your API integration does the filing work server-to-server — but your customers may still want to see their companies, documents, and filing statuses. Magic links give them that without you building UI or managing credentials.

How it works

curl -X POST https://api.fileforms.com/v1/auth/magic-link \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8" }'

{ "magicLink": "https://apps.fileforms.com/?token=..." }

• userId is required and must be one of your users — the link signs them into their own account.
• companyId is optional; when provided, the link lands the user directly on that company's page. The user must be an admin of the company.
• The link expires after 7 days and grants a normal dashboard session for that user.

If your organization has a white-label domain configured, the link points at your branded domain instead of apps.fileforms.com.

Usage patterns

• "View your filing" links — mint a fresh link when you email or notify your customer about a filing event, deep-linked to the company.
• Embedded access — an "Open compliance dashboard" button in your product that calls your backend, mints a link, and redirects — or an iframe, below.

Mint links on demand rather than storing them: they're single-purpose URLs with a 7-day shelf life, and each call returns a fresh one.

Embedding in an iframe

The dashboard can be embedded directly in your product with an iframe whose src is a freshly minted magic link:

<iframe
  src="https://apps.fileforms.com/?token=..."
  style="width: 100%; height: 100%; border: 0"
></iframe>

The flow: when your page loads, your frontend asks your backend for an embed URL, your backend calls POST /auth/magic-link (server-side — never expose your API key to the browser), and you set the returned URL as the iframe src.

Mint a fresh link on every load. Magic link tokens are single-use — once the iframe authenticates with one, that URL is spent. The session it creates lives in the embedded frame's browser storage, which browsers partition and may clear between visits, so don't count on it surviving. Treat the magic link as the way in every time: fresh page load, fresh POST /auth/magic-link, fresh src.