Autenticación

Envía tu clave de API hm_live_ como token Bearer. Cómo crear claves, elegir ámbitos, fijar la caducidad, rotarlas y revocarlas, y qué significa cada error.

Actualizado el 18 de octubre de 2026

Cada solicitud a la HILLS API envía una clave de API en la cabecera Authorization. No hay sesiones ni cookies: la API ignora las cookies y no envía cabeceras CORS. Llámala solo desde tu servidor.

La clave

Una clave tiene el formato hm_live_ seguido de 48 caracteres hexadecimales. Hay un solo tipo de clave. Lee y actúa sobre tu cuenta de socio y sobre los artistas y sellos que dependen de ella.

Las claves de prueba (hm_test_…) se retiraron el 12 de octubre de 2026 y responden 401 test_keys_retired. Para probar una entrega DDEX, usa la misma clave hm_live_ con POST /ddex/validate o la carpeta SFTP /test. Ninguna de las dos crea nada. Consulta Carpeta de pruebas.

Crea una clave

Las claves se crean en la aplicación web de HILLS, en la página Developers (/dashboard/developers), con New API key. Tienes que ser el propietario de la cuenta o tener un rol en el equipo con el permiso de claves de API. La API se incluye en los planes Enterprise y Custom. Con otros planes no puedes crear claves, y las existentes responden 403 api_not_in_plan.

Para cada clave eliges:

Un nombre. Indica dónde se usa, por ejemplo ERP sync o website.
Ámbitos. Lo que la clave puede hacer. Más información abajo.
Caducidad. Un número de días, o ninguna.

La clave completa se muestra una sola vez, al crearla. Después, las listas solo muestran su prefijo (por ejemplo, hm_live_ab12cd34). Si la pierdes, crea una nueva.

Envía la clave

Envíala como token Bearer:

curl "https://api.hillsmusic.com/v1/me" \
  -H "Authorization: Bearer $HILLS_API_KEY"

const HILLS = "https://api.hillsmusic.com/v1";

export async function hills(path, init = {}) {
  const res = await fetch(HILLS + path, {
    ...init,
    headers: { ...init.headers, Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
  });
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error), { status: res.status, code: body.code });
  return body;
}

console.log(await hills("/me"));

GET /me y GET /ping funcionan con cualquier clave válida, tenga los ámbitos que tenga. Úsalos para comprobar una clave. Consulta Cuenta.

Ámbitos

Cada clave tiene sus propios ámbitos. Un endpoint que necesita un ámbito que la clave no tiene responde 403 insufficient_scope, con el ámbito que falta en scope.

Ámbito	Qué permite
`members:read`	Consultar tus artistas y sellos.
`members:write`	Invitar a nuevos artistas y sellos.
`catalog:read`	Lanzamientos, pistas y su entrega a las plataformas.
`earnings:read`	Ingresos por mes, lanzamiento o plataforma.
`payouts:read`	Tu saldo y tus solicitudes de retiro.
`links:read`	Smart links y pre-saves con sus estadísticas.
`ddex:write`	Entregar lotes DDEX ERN y consultar su estado. También permite pruebas.
`ddex:validate`	Solo probar lotes DDEX. No se crea nada.
`webhooks:read`	Consultar los endpoints de webhook y sus entregas.
`webhooks:write`	Gestionar endpoints de webhook, secretos, eventos de prueba y reintentos.

Las claves nuevas empiezan con los cinco ámbitos de lectura: members:read, catalog:read, earnings:read, payouts:read y links:read. Los ámbitos de escritura, de DDEX y de webhooks nunca están activados por defecto.

Da a cada sistema su propia clave, solo con los ámbitos que necesita. Un proceso de informes necesita earnings:read, no ddex:write. Un proceso de CI que comprueba archivos DDEX solo necesita ddex:validate.

Rota una clave

Una clave no se rota por sí sola. Para sustituirla sin interrupciones:

Crea una clave nueva con los mismos ámbitos.
Despliégala en tu sistema.
Comprueba que el tráfico ha pasado a la nueva. La lista de claves muestra cuándo se usó cada una por última vez.
Revoca la clave antigua.

Revoca una clave

En la página Developers, abre el menú de la clave y elige Revoke. Deja de funcionar al instante y responde 401 key_revoked. Revoca una clave de inmediato si se filtra, por ejemplo, si se subió a un repositorio o se pegó en un chat.

Cada clave tiene además un registro de solicitudes. Selecciona una clave en la lista para ver sus solicitudes recientes: método, ruta, estado y hora. Las solicitudes se conservan 7 días.

Errores de autenticación

Estado	`code`	Qué hacer
401	`unauthenticated`	Falta la cabecera `Authorization: Bearer`. Añádela.
401	`invalid_key`	La clave no existe o está mal escrita. Comprueba que no haya espacios ni un valor cortado.
401	`key_revoked`	La clave se revocó. Crea una nueva.
401	`key_expired`	La clave superó su fecha de caducidad. Crea una nueva.
401	`test_keys_retired`	Una clave `hm_test_` antigua. Usa una clave `hm_live_`.
403	`insufficient_scope`	A la clave le falta el ámbito indicado en `scope`. Crea una clave que lo tenga.
403	`account_inactive`	Tu cuenta no está activa. Ponte en contacto con HILLS Music.
403	`api_not_in_plan`	Tu plan no incluye la API. Se incluye en Enterprise y Custom.

Todos los errores tienen la misma forma. Consulta Errores.

Mantén las claves a salvo

Guarda las claves en un gestor de secretos o en variables de entorno, no en el código.
Nunca pongas una clave en una página web, una aplicación móvil o una aplicación de escritorio. Ahí cualquiera puede leerla.
Usa una clave por sistema, para poder revocar una sin detener las demás.
Pon caducidad a las claves de proyectos cortos y de colaboradores externos.