Autenticación

La autenticación para el embebido requiere dos pasos: generar un JWT y crear una firma RSA del request.

1. Generar el JWT (HS256)

Crea un JSON Web Token con los datos del usuario autenticado en tu plataforma.

Payload

Campo	Tipo	Requerido	Descripción
sub	string	Sí	Tu hostId
email	string	Sí	Email del usuario
name	string	Sí	Nombre del usuario
paternalLastName	string	Sí	Apellido paterno
maternalLastName	string	No	Apellido materno
iss	string	Sí	Tu clientId

Header

Campo	Valor
alg	HS256
kid	Tu clientId

Ejemplo

auth.js

import jwt from "jsonwebtoken";

const jwtPayload = {
  sub: process.env.CM_HOST_ID,
  email: user.email,
  name: user.firstName,
  paternalLastName: user.lastName.split(" ")[0],
  ...(user.lastName.split(" ")[1] && {
    maternalLastName: user.lastName.split(" ")[1],
  }),
  iss: process.env.CM_CLIENT_ID,
};

const token = jwt.sign(jwtPayload, process.env.CM_JWT_SECRET, {
  algorithm: "HS256",
  expiresIn: "5m",
  header: {
    kid: process.env.CM_CLIENT_ID,
    alg: "HS256",
  },
});

Nota

El JWT tiene una expiración de 5 minutos. Se usa únicamente para la solicitud de autorización, no para la sesión del usuario en el marketplace.

2. Firmar el request (RSA-SHA256)

Cada solicitud al API debe incluir una firma digital creada con tu llave privada RSA.

Construir el payload a firmar

El payload de firma se construye concatenando los siguientes valores separados por \n:

{method}\n{url}\n{timestamp}\n{body}\n{headers}

Parte	Descripción	Ejemplo
method	Método HTTP	GET
url	Path del endpoint	/hosts/{hostId}/authorize-user
timestamp	Date.now().toString()	1710000000000
body	Body serializado (vacío si GET)	""
headers	Headers ordenados, formato key:value	Ver abajo

Headers incluidos en la firma

headers-to-sign.js

const headersToSign = {
  "content-type": "application/json",
  "x-cm-host-id": hostId,
  "x-cm-client-id": clientId,
  authorization: `Bearer ${token}`,
};

Los headers se ordenan alfabéticamente y se unen con \n en formato key:value.

Ejemplo completo

sign-request.js

import { createSign } from "crypto";
import { readFileSync } from "fs";

async function signRequest(clientId, method, url, body, hostId, token) {
  const privateKey = readFileSync("./keys/private.pem", "utf8");
  const timestamp = Date.now().toString();

  const headersToSign = {
    "content-type": "application/json",
    "x-cm-host-id": hostId,
    "x-cm-client-id": clientId,
    authorization: `Bearer ${token}`,
  };

  const headerLines = Object.entries(headersToSign)
    .map(([k, v]) => `${k}:${v}`)
    .join("\n");

  const bodyStr = body ? JSON.stringify(body) : "";
  const payload = `${method}\n${url}\n${timestamp}\n${bodyStr}\n${headerLines}`;

  const signer = createSign("RSA-SHA256");
  signer.update(payload);
  signer.end();

  const signature = signer.sign(privateKey).toString("base64");

  return { signature, timestamp };
}

Importante

• El timestamp debe ser el mismo que envías en el header X-CM-Timestamp
• La firma se codifica en Base64
• La llave privada debe leerse desde un archivo seguro, nunca hardcodeada

Siguiente paso

Con el JWT y la firma listos, procede a Obtener el Token.