Portal

Sign your customers into their billing portal from your own app or dashboard.

There is no public sign-in page and no self-service link request: a customer reaches the portal only through you. Your app authenticates the customer, asks Kontier for a sign-in link with your API key, and sends the browser there at once.

The flow

1. Authenticate the customer in your own app, as you do today.
2. Find their Kontier customer: GET /v1/customers?email=jane@example.com (or keep the customer id you stored when you created them).
3. Issue a link: POST /v1/customers/{id}/portal-links with a short ttl_seconds and, if you want, a return_path.
4. Redirect the browser to the returned url at once. The customer lands signed in, on return_path if you gave one.

Code
curl -X POST https://api.kontier.eu/v1/customers/$CUSTOMER_ID/portal-links \
  -H "Authorization: Bearer $KONTIER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 120, "return_path": "/portal/invoices"}'

Code
{"data": {"url": "https://app.example.com/portal/enter/eyJhbGciOi...", "token": "eyJhbGciOi...", "expires_at": "2026-10-25T10:02:00Z"}}

Every POST needs an Idempotency-Key. Use a new one for each sign-in: a retry with the same key replays the first answer, which is the same single-use link.

Security contract

• Authenticate your customer first. Whoever holds the URL is signed in as that customer.
• Redirect, do not send. Never email, log or store the link unless delivering it is what you mean to do.
• Links are single-use and short-lived. A link signs in once; opening it again lands on the portal's expired page, exactly as an expired link does. It lives for ttl_seconds (60 up to the deployment's link TTL, 30 minutes unless configured otherwise). Ask for 60 to 120 seconds when you redirect at once. Links issued before single-use links were introduced carry no single-use id and are refused: issue a new one.
• Scope your key. The endpoint needs the portal.links.issue permission (area Portal Sign-in in the key's custom access). Give the key that signs customers in that permission and only what else it needs. Keys that held customer.write before this permission existed were granted it once, so existing integrations keep working.

return_path must be one of the portal's own pages, such as /portal/invoices, /portal/invoices/{id}/pay, /portal/quote/{id} or /portal/subscriptions/{id}. Anything else (another host, a query, //) is refused with 400.

Each link you issue is recorded in the audit log as customer.portal_access_issued: who issued it, for which customer, the landing page and the expiry. The link itself is never stored.