The Embeddable Components module doesn't directly communicate with the Maxio Advanced Billing API. Rather, it leverages the Embeddable Components Backend (ECB) to handle all frontend requests, perform authentication, and transform the data into a format that can be consumed by the Advanced Billing API. The responses are then mapped back to the Embeddable Components module, in suitable form.
Communication Between Frontend and the Backend
All requests made by the Embeddable Components come 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 lowered using the exp claim, but it cannot be longer than one hour. It's possible to add a second Token Sign in Key to allow for key rotation without downtime. The Embeddable Components Backend would 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 that specify 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 the patterns stored in the database. It then proceeds to the next step of JWT authorization for sites that only match the filtered patterns. The domain patterns can either be exact domains (for example, keen.io, sub.keen.io) or patterns that use wildcards (like *keen.io or *n.io).
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 easily test their integrations locally.
Authentication Endpoint
The Authentication Endpoint is a minimal backend component that merchants need to 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 that the components know where to fetch the token from.
The endpoint should return a JSON object with the token field containing the signed token value.
For example:
{”token”: “eyJg…”}
The token should be signed using the Base64 decoded Token Sign in Key.
The subject of the token should be set to the Maxio customer reference of a customer referring to an authenticated user in the Merchant's application. The iat (issued at) claim must be included in the token.
Token payload:
-
sub (subject)
Required string. Matches the customer reverence in Advanced Billing. -
iat (issued at)
Required timestamp. Used for token expiration validation. By default, the token is rejected if it's older than one hour. -
exp (expiration)
Optional timestamp. Used for token expiration validation. Due to security reasons, you can only decrease the default token expiration to less than an hour. The token is rejected ifexpis set to a time that is greater than one hour.
For Authentication endpoint examples, see the Code Samples article.