Autenticación

Auth emite tokens OAuth 2.0. Los endpoints protegidos reciben el token en Authorization; los endpoints públicos no lo necesitan. Revisa la seguridad de cada operación en su referencia.

Credenciales de aplicación

Una aplicación OAuth creada desde el panel entrega client_id y client_secret. El secreto identifica a un servidor, por lo que no debe llegar al navegador ni a una aplicación distribuida.

Una API key creada con POST /v1/api-keys pertenece al servicio UCP, cuya referencia aún no está publicada.

No sirve en /connect/token y ninguna operación de Admin, Storefront o Auth la acepta.

Para esas APIs, usa el token Bearer indicado en cada operación.

Token para una integración de Admin

Usa client_credentials e incluye el scope api_admin:

curl -X POST https://auth.ecomiq.pe/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$ECOMIQ_CLIENT_ID" \
  -d "client_secret=$ECOMIQ_CLIENT_SECRET" \
  -d "scope=api_admin"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600
}

expires_in indica la vigencia en segundos de esa respuesta. Calcula la caducidad con ese valor en vez de asumir una duración fija.

Usar el token

curl "https://api.ecomiq.pe/api/v1/catalog/products?limit=25" \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

Admin también necesita contexto de tienda y, cuando aplica, de vendedor. En el flujo público documentado aquí, ese contexto proviene de los claims del token. Consulta Contexto y jerarquía.

Grants

Grant	Uso
`client_credentials`	Un servidor actúa como la aplicación. Requiere un cliente confidencial y no devuelve sesión de usuario.
`authorization_code`	Un usuario inicia sesión y autoriza una aplicación configurada para este flujo.
`refresh_token`	Renueva una sesión cuando la aplicación y el token recibieron este grant.
`password`	Solo clientes propios configurados expresamente. No lo uses en integraciones de terceros.

La aplicación define qué grants y scopes acepta. No envíes un grant solo porque aparezca en esta tabla.

client_credentials no necesita un refresh token: solicita otro access token antes de que venza el actual. Cachea el token por proceso y aplica un margen breve para evitar usarlo durante su caducidad.

let cached: { token: string; expiresAt: number } | undefined;

export async function getToken(): Promise<string> {
  if (cached && Date.now() < cached.expiresAt - 60_000) {
    return cached.token;
  }

  const body = new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.ECOMIQ_CLIENT_ID!,
    client_secret: process.env.ECOMIQ_CLIENT_SECRET!,
    scope: "api_admin",
  });

  const response = await fetch("https://auth.ecomiq.pe/connect/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body,
  });

  if (!response.ok) throw new Error(`OAuth HTTP ${response.status}`);

  const payload = await response.json();
  cached = {
    token: payload.access_token,
    expiresAt: Date.now() + payload.expires_in * 1000,
  };

  return cached.token;
}

Coordina la renovación si varios procesos comparten credenciales. Así evitas una ráfaga de solicitudes de token al mismo tiempo.

Fallos de autenticación

401 indica que el endpoint no recibió una credencial válida.
403 indica que la identidad fue aceptada, pero una política, scope, permiso o contexto impidió la operación.
/connect/token devuelve errores OAuth como invalid_client o invalid_grant; no asumas que usa Problem Details ni el campo code.

No registres el token, el secreto ni el cuerpo completo de una respuesta OAuth.