# 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.

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](https://developer.hillsmusic.com/es/reference/ddex-deliveries/#test-a-ddex-message-or-batch) o la carpeta SFTP `/test`. Ninguna de las dos crea nada. Consulta [Carpeta de pruebas](https://developer.hillsmusic.com/es/reference/test-folder/).

## 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:

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

```js
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](https://developer.hillsmusic.com/es/reference/account/).

## Á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:

1. Crea una clave nueva con los mismos ámbitos.
2. Despliégala en tu sistema.
3. Comprueba que el tráfico ha pasado a la nueva. La lista de claves muestra cuándo se usó cada una por última vez.
4. 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](https://developer.hillsmusic.com/es/guides/errors/).

## 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.

Fuente: https://developer.hillsmusic.com/es/guides/authentication/