Help Center › Configuration › Advanced Billing › Embeddable Components

Embeddable Components Code Samples

··

Last updated on Aug 26, 2026

Working samples for the two pieces you build when you integrate Embeddable Components: the frontend that installs and initializes the package, and the backend authentication endpoint that issues signed tokens. The JWT samples cover Python, Node.js, Go, Java, and .NET.

Frontend

Install the components dependency with your package manager.

Using pnpm:

bash

pnpm install @maxio-com/self-service

Using npm:

bash

npm install @maxio-com/self-service

Using yarn:

bash

yarn add @maxio-com/self-service

Then initialize componentsFactory in your application code:

javascript

let componentsFactory = new Components({
  i18nSettings: {
    loadPath: 'https://your-host.example.com/locales/en/{{ns}}.json',
    language: 'en',
  },
  accessTokenUrl: 'https://merchant.site/components/auth',
  theme: {
    colors: { colorpalette },
    components: {
      Button: { ...ButtonSettings, boxShadow: 'none' }
    },
  }
});

Properties of the Components object

Property	Description
`i18nSettings`	Localization settings. loadPath - URL where the label translations live. Use localization provided by Maxio, or host your own. language - The language to load.
`accessTokenUrl`	URL of your authentication endpoint, which issues the tokens that authenticate Maxio Customers against the components backend.
`apiUrl`	URL of the Embeddable Components backend. Defaults to `https://selfservice.maxio.com/api/`.
`onAuthenticationRequest`	Customizes the authentication request to your backend, for example by adding a custom authentication header.
`theme`	Styles and overrides the components' appearance.

Theming

Include the theme property in the componentsFactory constructor:

javascript

theme: {
  colors: { colorpalette },
  fontWeights: "1",
  components: {
    Button: { ...ButtonSettings, boxShadow: 'none' },
  },
}

You can customize the whole color palette, most standard text formatting options, and the granular settings of each individual component, such as button, credit card, or input.

Backend authentication endpoint

The endpoint returns a JSON object with a token field holding the signed token value:

json

{"token": "eyJg…"}

Set the token subject to the Maxio Customer reference for the authenticated user in your application. Sign the token with the JWT key issued when you launched the integration, using the HS256 algorithm, and include the iat (issued at) claim.

In each sample below, customer_reference is the Maxio Customer's reference field resolved from your authenticated user, and the key is the secret shown in the Maxio UI.

Python

python

# Install the PyJWT package using pip, or include it in your requirements.txt.
import base64
from datetime import datetime
import json
from jwt.api_jwt import PyJWT
 
payload = {
    "sub": customer_reference,
    "iat": datetime.utcnow().timestamp()
}
 
decoded_key = base64.b64decode(key)
jwt_token = PyJWT().encode(payload=payload, key=decoded_key)
response_body = json.dumps({"token": jwt_token})

Node.js

typescript

// Add the jsonwebtoken dependency to the project, then:
module.post('/auth', (req: Request, res: Response) => {
    const token = jwt.sign(
        {},
        Buffer.from(MERCHANT_PRIVATE_KEY, 'base64'),
        {
            subject: customerReference,
            algorithm: 'HS256'
        }
    );
    res.status(StatusCodes.OK);
    res.json({
        token,
    });
});

Go

// Add the github.com/golang-jwt/jwt/v5 package to the project, then:
import (
    "time"
    "encoding/base64"
    "github.com/golang-jwt/jwt/v5"
)
 
func main() {
    // Create a new token object
    token := jwt.New(jwt.SigningMethodHS256)
 
    // Set the claims for the token
    claims := token.Claims.(jwt.MapClaims)
    claims["sub"] = customer_reference
    claims["iat"] = time.Now().Unix()
 
    // Sign the token with the secret key
    decoded_key, _ := base64.StdEncoding.DecodeString(secretKey)
    signedToken, _ := token.SignedString(decoded_key)
}

Java

java

// Add these dependencies to the project:
//   io.jsonwebtoken.jjwt-api
//   io.jsonwebtoken.jjwt-impl
//   io.jsonwebtoken.jjwt-jackson
 
Key key = Keys.hmacShaKeyFor(Base64.getDecoder().decode(base64Key));
String jw = Jwts.builder()
    .setIssuedAt(new Date())
    .setSubject(customer_reference)
    .signWith(key)
    .compact();

.NET

csharp

// Add the JWT dependency to the project: dotnet add package System.IdentityModel.Tokens.Jwt
var signingKey = new SymmetricSecurityKey(Convert.FromBase64String(secretKey));
var signingCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256);
 
// Create the JWT token
var claims = new[]
{
    new Claim("sub", customer_reference),
    new Claim("iat", DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString())
};
 
var token = new JwtSecurityToken(
    claims: claims,
    signingCredentials: signingCredentials
);
 
// Encode the JWT token as a string
var encodedToken = new JwtSecurityTokenHandler().WriteToken(token);

For how the components authenticate against the API, including the domain rules and token claims, see the Understand Embeddable Components Authentication help article.

To enable the integration and generate a sign-in key, see the Set Up Embeddable Components for Self-Service Subscription Management help article.

Still need help?
Reach out and our support team will take it from here.

Contact support

Help Center › Configuration › Advanced Billing › Embeddable Components

Embeddable Components Code Samples

··

Last updated on Aug 26, 2026

Frontend

Install the components dependency with your package manager.

Using pnpm:

bash

pnpm install @maxio-com/self-service

Using npm:

bash

npm install @maxio-com/self-service

Using yarn:

bash

yarn add @maxio-com/self-service

Then initialize componentsFactory in your application code:

javascript

let componentsFactory = new Components({
  i18nSettings: {
    loadPath: 'https://your-host.example.com/locales/en/{{ns}}.json',
    language: 'en',
  },
  accessTokenUrl: 'https://merchant.site/components/auth',
  theme: {
    colors: { colorpalette },
    components: {
      Button: { ...ButtonSettings, boxShadow: 'none' }
    },
  }
});

Properties of the Components object

Property	Description
`i18nSettings`	Localization settings. loadPath - URL where the label translations live. Use localization provided by Maxio, or host your own. language - The language to load.
`accessTokenUrl`	URL of your authentication endpoint, which issues the tokens that authenticate Maxio Customers against the components backend.
`apiUrl`	URL of the Embeddable Components backend. Defaults to `https://selfservice.maxio.com/api/`.
`onAuthenticationRequest`	Customizes the authentication request to your backend, for example by adding a custom authentication header.
`theme`	Styles and overrides the components' appearance.

Theming

Include the theme property in the componentsFactory constructor:

javascript

theme: {
  colors: { colorpalette },
  fontWeights: "1",
  components: {
    Button: { ...ButtonSettings, boxShadow: 'none' },
  },
}

You can customize the whole color palette, most standard text formatting options, and the granular settings of each individual component, such as button, credit card, or input.

Backend authentication endpoint

The endpoint returns a JSON object with a token field holding the signed token value:

json

{"token": "eyJg…"}

In each sample below, customer_reference is the Maxio Customer's reference field resolved from your authenticated user, and the key is the secret shown in the Maxio UI.

Python

python

# Install the PyJWT package using pip, or include it in your requirements.txt.
import base64
from datetime import datetime
import json
from jwt.api_jwt import PyJWT
 
payload = {
    "sub": customer_reference,
    "iat": datetime.utcnow().timestamp()
}
 
decoded_key = base64.b64decode(key)
jwt_token = PyJWT().encode(payload=payload, key=decoded_key)
response_body = json.dumps({"token": jwt_token})

Node.js

typescript

// Add the jsonwebtoken dependency to the project, then:
module.post('/auth', (req: Request, res: Response) => {
    const token = jwt.sign(
        {},
        Buffer.from(MERCHANT_PRIVATE_KEY, 'base64'),
        {
            subject: customerReference,
            algorithm: 'HS256'
        }
    );
    res.status(StatusCodes.OK);
    res.json({
        token,
    });
});

Go

// Add the github.com/golang-jwt/jwt/v5 package to the project, then:
import (
    "time"
    "encoding/base64"
    "github.com/golang-jwt/jwt/v5"
)
 
func main() {
    // Create a new token object
    token := jwt.New(jwt.SigningMethodHS256)
 
    // Set the claims for the token
    claims := token.Claims.(jwt.MapClaims)
    claims["sub"] = customer_reference
    claims["iat"] = time.Now().Unix()
 
    // Sign the token with the secret key
    decoded_key, _ := base64.StdEncoding.DecodeString(secretKey)
    signedToken, _ := token.SignedString(decoded_key)
}

Java

java

// Add these dependencies to the project:
//   io.jsonwebtoken.jjwt-api
//   io.jsonwebtoken.jjwt-impl
//   io.jsonwebtoken.jjwt-jackson
 
Key key = Keys.hmacShaKeyFor(Base64.getDecoder().decode(base64Key));
String jw = Jwts.builder()
    .setIssuedAt(new Date())
    .setSubject(customer_reference)
    .signWith(key)
    .compact();

.NET

csharp

// Add the JWT dependency to the project: dotnet add package System.IdentityModel.Tokens.Jwt
var signingKey = new SymmetricSecurityKey(Convert.FromBase64String(secretKey));
var signingCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256);
 
// Create the JWT token
var claims = new[]
{
    new Claim("sub", customer_reference),
    new Claim("iat", DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString())
};
 
var token = new JwtSecurityToken(
    claims: claims,
    signingCredentials: signingCredentials
);
 
// Encode the JWT token as a string
var encodedToken = new JwtSecurityTokenHandler().WriteToken(token);

For how the components authenticate against the API, including the domain rules and token claims, see the Understand Embeddable Components Authentication help article.

To enable the integration and generate a sign-in key, see the Set Up Embeddable Components for Self-Service Subscription Management help article.

Still need help?
Reach out and our support team will take it from here.

Contact support

Embeddable Components Code Samples

Frontend

Theming

Backend authentication endpoint

Python

Node.js

Go

Java

.NET

Related information

Embeddable Components Code Samples

Frontend

Theming

Backend authentication endpoint

Python

Node.js

Go

Java

.NET

Related information