Docs / Autenticación

Autenticación de la API

Todos los módulos de la API de Webability — DNS, Imágenes, Mail, Marketing y Video — comparten exactamente el mismo esquema de autenticación. Esta página es la referencia única: los manuales de cada módulo enlazan aquí en vez de repetir el contenido.

Introducción

Cada cuenta tiene un par de credenciales: un Client ID (público, identifica la cuenta) y un Token (secreto, nunca viaja en el request). En vez de enviar el token directamente, cada petición se firma con un HMAC-SHA256 calculado sobre un mensaje canónico corto, usando el token como clave secreta. El servidor recalcula el mismo HMAC con el token que tiene almacenado y compara ambos resultados.

¿Por qué así?

• El token nunca se transmite, ni siquiera cifrado
• Cada request queda ligado a su método, ruta y momento exacto
• Una petición capturada no puede reenviarse pasados 300 segundos

Dónde obtener tus credenciales

• Consola → Configuración
• Un Client ID y Token por cuenta, compartido por todos los módulos
• Puedes regenerar el Token en cualquier momento desde la consola

Headers requeridos

Toda petición autenticada debe incluir estos tres headers HTTP.

Header	Descripción
X-WA-Client	Tu Client ID (público)
X-WA-Timestamp	Timestamp Unix actual (segundos). La petición expira en ±300 s respecto al reloj del servidor.
X-WA-Digest	HMAC-SHA256 del mensaje canónico (firmado con tu Token secreto), en hexadecimal.

Mensaje canónico

El digest se calcula sobre esta cadena, en este orden exacto, separada por |:

{METHOD}|{PATH}|{TIMESTAMP}|{CLIENTID}

Ejemplo para POST /v1/dns/zone: POST|/v1/dns/zone|1720000000|miclientid

METHOD es el verbo HTTP en mayúsculas (GET, POST, PUT, DELETE). PATH es la ruta absoluta sin host ni query string (p. ej. /v1/dns/zone/42).

Tus credenciales

🔑 Inicia sesión para ver tus credenciales aquí mismo — Iniciar sesión · Crear cuenta gratis

El mismo Client ID y Token funcionan para todos los módulos (DNS, Imágenes, Mail, Marketing, Video). No necesitas credenciales distintas por módulo.

Ejemplos de firma por lenguaje

Cálculo del digest para GET /v1/dns/zone. El patrón es idéntico para cualquier módulo — solo cambia PATH y METHOD.

Bash (curl + openssl)

CLIENTID="[IDCliente]"
TOKEN="[TokenCliente]"
TS=$(date +%s)
METHOD="GET"
PATH="/v1/dns/zone"
MSG="${METHOD}|${PATH}|${TS}|${CLIENTID}"
DIG=$(echo -n "$MSG" | openssl dgst -sha256 -hmac "$TOKEN" | awk '{print $2}')

curl -s https://api.webability.info${PATH} \
  -H "X-WA-Client: $CLIENTID" \
  -H "X-WA-Timestamp: $TS" \
  -H "X-WA-Digest: $DIG"

import (
  "crypto/hmac"
  "crypto/sha256"
  "fmt"
  "time"
)

func sign(clientID, token, method, path string) (ts, digest string) {
  ts = fmt.Sprintf("%d", time.Now().Unix())
  msg := method + "|" + path + "|" + ts + "|" + clientID
  mac := hmac.New(sha256.New, []byte(token))
  mac.Write([]byte(msg))
  digest = fmt.Sprintf("%x", mac.Sum(nil))
  return
}

JavaScript (Node.js)

const crypto = require('crypto');

function sign(clientId, token, method, path) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const msg = `${method}|${path}|${ts}|${clientId}`;
  const digest = crypto.createHmac('sha256', token).update(msg).digest('hex');
  return { ts, digest };
}

PHP

$clientId = '[IDCliente]';
$token = '[TokenCliente]';
$method = 'GET';
$path = '/v1/dns/zone';
$ts = (string) time();
$msg = "$method|$path|$ts|$clientId";
$digest = hash_hmac('sha256', $msg, $token);

Python

import hmac, hashlib, time

def sign(client_id, token, method, path):
    ts = str(int(time.time()))
    msg = f"{method}|{path}|{ts}|{client_id}"
    digest = hmac.new(token.encode(), msg.encode(), hashlib.sha256).hexdigest()
    return ts, digest

Rust

use hmac::{Hmac, Mac};
use sha2::Sha256;

type HmacSha256 = Hmac<Sha256>;

fn sign(client_id: &str, token: &str, method: &str, path: &str, ts: &str) -> String {
    let msg = format!("{method}|{path}|{ts}|{client_id}");
    let mut mac = HmacSha256::new_from_slice(token.as_bytes()).unwrap();
    mac.update(msg.as_bytes());
    hex::encode(mac.finalize().into_bytes())
}

C (OpenSSL)

unsigned char md[EVP_MAX_MD_SIZE];
unsigned int md_len;
HMAC(EVP_sha256(),
     token, (int)strlen(token),
     (const unsigned char *)msg, strlen(msg),
     md, &md_len);
/* convierte md[0..md_len) a hex para X-WA-Digest */

Usa un SDK oficial

Los SDKs oficiales firman cada petición automáticamente — no necesitas implementar HMAC-SHA256 a mano. Solo inicializas el cliente con tu Client ID y Token, y cada llamada queda firmada por debajo.

Errores comunes de autenticación

El código numérico exacto varía según el módulo (cada uno tiene su propia tabla de errores en su manual), pero las tres causas posibles son siempre las mismas:

HTTP	Causa	Solución
401	Faltan uno o más de los headers X-WA-Client / X-WA-Timestamp / X-WA-Digest	Verifica que los tres headers se envíen en cada request
401	Firma HMAC inválida, o el timestamp está fuera de la ventana de ±300 s	Revisa el mensaje canónico (orden y valores exactos) y que el reloj de tu servidor esté sincronizado (NTP)
401	El Token no corresponde a ninguna cuenta	Confirma el Token vigente en Consola → Configuración — pudo haberse regenerado

Buenas prácticas

• Nunca coloques el Token en código de frontend/JavaScript de navegador — fírmalo siempre desde tu backend.
• Guarda el Token como variable de entorno o secreto, no en el repositorio.
• Sincroniza el reloj de tus servidores (NTP) para evitar rechazos por timestamp fuera de rango.
• Si sospechas que tu Token se filtró, regénéralo de inmediato desde la consola — invalida el anterior al instante.