Integration

Addresses and domains

How a module address comes into being, what changes when a customer connects their own domain, and how to build addresses in code.

Three kinds of address

KindExamplePurpose
Workspace addressacme.crm.blesyum.appThe product's canonical door
Bare module addresscrm.blesyum.appRedirects to the marketing page
Customer domainsupport.acme.comThe domain the customer connected

The workspace address appears by itself

The moment a module is licensed, its workspace-specific address is created. No request, no support ticket, no waiting.

text
<slug>.<module>.blesyum.app

The bare address is NOT a sign-in door

A visitor arriving at crm.blesyum.app with a browser is 302-redirected to the product's marketing page. But machine paths still work there:

  • /api/&lt;module&gt;/* — webhook inbound, OAuth callbacks
  • /api/v1/* — core
  • /.well-known/* — domain ownership verification

That split is deliberate: if you registered an OAuth callback on the bare host, it keeps working.

When a customer connects their own domain

If a customer connects a domain and points it at a module, that is the module's address. The platform address keeps working but browser requests are 302-moved to the customer's.

For an integration this means exactly one thing:

Never hard-code an address. An integration with https://acme.crm.blesyum.app written in starts looking at the wrong address the day the customer connects their own domain (it still works, but it is no longer canonical; link generation and SSO returns break).

The correct source:

bash
curl "https://accounts.blesyum.com/api/v1/modules" \
  -H "Authorization: Bearer <session-token>"
json
{ "data": [
    { "key": "crm", "label": "CRM", "licensed": true,
      "url": "https://support.acme.com",
      "openapi_url": "https://support.acme.com/api/crm/public/v1/openapi.json" }
] }

The url field is the effective address: the customer's domain if one is connected, the platform address otherwise.

One module, one address

Only one customer domain can point at a module at a time. That removes the "which one is canonical" question — links, emails, SSO returns and search engines all see a single address.

The Commerce exception

In Commerce the customer's domain opens the storefront; the admin panel lives on a separate origin:

text
acme.shop.blesyum.app          → storefront (what shoppers see)
acme--panel.shop.blesyum.app   → admin panel

API paths (/api/shop/v1/...) work on both.

TLS

Every workspace address obtains its certificate on demand. When a new module is licensed the address is ready within seconds; there is no separate step.