Under the Hood

The Embeddable Components module in Maxio simplifies frontend integration by securely interfacing with the Advanced Billing API. Through its Embeddable Components Backend (ECB), it handles authentication, CORS filtering, and JSON Web Token (JWT) validation, ensuring safe and streamlined data transactions for SaaS applications.

Communication Between Frontend and the Backend

All requests made by the Embeddable Components originate from a web browser application provided by the Merchant. To authenticate with the Embeddable Components Backend, Merchants must provide a JSON Web Token (JWT) signed with the Token Sign-in Key, which is generated when launching the integration.

This generated sign-in key is Base64 encoded. The token should contain a subject claim equal to the Maxio Customer reference (which maps the Merchant's internal user representation to the Customer reference at Maxio).

The Embeddable Components Backend verifies the token signature using the Token Sign-in Key. This allows requests to be executed on behalf of a specific user while maintaining security. The token's claim issued at date is validated using the site's maximum token expiration time, which is currently one hour. This can be reduced using the exp claim, but it cannot be longer than one hour. You can add a second Token Sign-in Key to allow for key rotation without downtime. The Embeddable Components Backend will accept both keys to verify the token signature.

The Embeddable Components Backend also uses Cross-Origin Resource Sharing (CORS) to filter and match requests. Merchants can configure a set of Origin patterns specifying the sites where they want to embed the components. When a request is received by the backend, it first filters the provided Origin against all patterns stored in the database. It then proceeds to JWT authorization only for sites matching the filtered patterns. Domain patterns can be exact (e.g., keen.io, sub.keen.io) or use wildcards (e.g., *.keen.io, *.n.io).

The Token Sign-in Key used to sign the JWT is scoped to a specific Maxio site, not to a general environment like “sandbox” or “production.” This means you must generate and use a separate token key for each site, even if both belong to the same Merchant.

In summary, CORS ensures the request originates from an allowed domain, while the JWT ensures the request is made on behalf of an authenticated Customer. These checks operate independently but sequentially to secure the integration.

Additionally, the pattern must have at least two segments. However, an exception is made for localhost, which is an allowed origin to enable Merchants to test their integrations locally.

Authentication Endpoint

The Authentication Endpoint is a minimal backend component that Merchants must provide for their Embeddable Components. This endpoint is used by the components to fetch the token required to sign requests to the Embeddable Components Backend using the Merchant Application backend for the authenticated user. Merchants need to specify the URL of this endpoint in the components' frontend initialization code so the components know where to fetch the token.

The endpoint should return a JSON object with a token field containing the signed token value.

For example:

{"token": "eyJg…"}

The token must be signed using the Base64-decoded Token Sign-in Key.

The subject of the token should be set to the Maxio Customer reference representing the authenticated user in the Merchant's application. The iat (issued at) claim must be included.

Token payload:

• sub (subject)
  Required string. Matches the Customer reference in Advanced Billing.
• iat (issued at)
  Required timestamp. Used for token expiration validation. By default, the token is rejected if older than one hour.
• exp (expiration)
  Optional timestamp. Used for token expiration validation. For security, you can only decrease the default expiration. Tokens with exp set to more than one hour are rejected.

For Authentication endpoint examples, see the Code Samples article.

Why Customer Reference Instead of Customer ID?

Maxio Embeddable Components use the customer_reference in the JWT's sub (subject) claim because authentication is performed within your system. This allows you to map internal user IDs to Maxio Customers without exposing Maxio-specific identifiers.

If you're not currently using Customer references, you can assign a reference for each Customer — such as your internal customer_id — via the Maxio API or through a Customer import. This flexibility allows for safer, more decoupled authentication between systems.