# Xác thực

> Gửi API key hm_live_ dưới dạng Bearer token. Cách tạo key, chọn scope, đặt thời hạn, xoay vòng và thu hồi key, và ý nghĩa của từng lỗi xác thực.

Mọi request đến HILLS API đều gửi một API key trong header `Authorization`. Không có session và không có cookie: API bỏ qua cookie và không gửi header CORS. Chỉ gọi API từ server của bạn.

## Key

Một key có dạng `hm_live_` theo sau là 48 ký tự hex. Chỉ có một loại key. Key đọc và thao tác trên tài khoản khách hàng của bạn cùng các nghệ sĩ và hãng đĩa thuộc tài khoản đó.

Key test (`hm_test_…`) đã ngừng sử dụng từ ngày 12/10/2026 và trả về `401 test_keys_retired`. Để kiểm thử một lần phân phối DDEX, hãy dùng chính key `hm_live_` với [POST /ddex/validate](https://developer.hillsmusic.com/vi/reference/ddex-deliveries/#test-a-ddex-message-or-batch), hoặc thư mục SFTP `/test`. Cả hai đều không tạo ra gì. Xem [Thư mục test](https://developer.hillsmusic.com/vi/reference/test-folder/).

## Tạo key

Key được tạo trong ứng dụng web HILLS, trên trang **Developers** (`/dashboard/developers`), bằng nút **New API key**. Bạn cần là chủ tài khoản, hoặc có vai trò trong nhóm với quyền API keys. API đi kèm các gói Enterprise và Custom. Ở các gói khác bạn không tạo được key, và các key hiện có trả về `403 api_not_in_plan`.

Với mỗi key, bạn chọn:

- **Tên.** Ghi rõ key chạy ở đâu, ví dụ `ERP sync` hoặc `website`.
- **Scope.** Những gì key được phép làm. Xem bên dưới.
- **Thời hạn.** Số ngày, hoặc không hết hạn.

Key đầy đủ chỉ hiển thị một lần, lúc bạn tạo. Sau đó, danh sách chỉ hiện tiền tố (ví dụ `hm_live_ab12cd34`). Nếu làm mất key, hãy tạo key mới.

## Gửi key

Gửi key dưới dạng Bearer token:

```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` và `GET /ping` hoạt động với mọi key hợp lệ, dù key có scope nào. Hãy dùng chúng để kiểm tra key. Xem [Tài khoản](https://developer.hillsmusic.com/vi/reference/account/).

## Scope

Mỗi key có scope riêng. Endpoint cần một scope mà key không có sẽ trả về `403 insufficient_scope`, kèm scope còn thiếu trong `scope`.

| Scope | Cho phép làm gì |
| --- | --- |
| `members:read` | Liệt kê nghệ sĩ và hãng đĩa của bạn. |
| `members:write` | Mời nghệ sĩ và hãng đĩa mới. |
| `catalog:read` | Bản phát hành, track và việc phân phối chúng đến các nền tảng. |
| `earnings:read` | Doanh thu theo tháng, bản phát hành hoặc nền tảng. |
| `payouts:read` | Số dư và các yêu cầu rút tiền của bạn. |
| `links:read` | Smart link và pre-save cùng số liệu thống kê. |
| `ddex:write` | Phân phối các lô DDEX ERN và đọc trạng thái của chúng. Cũng cho phép kiểm thử. |
| `ddex:validate` | Chỉ kiểm thử các lô DDEX. Không có gì được tạo ra. |
| `webhooks:read` | Liệt kê endpoint webhook và các lần gửi đến chúng. |
| `webhooks:write` | Quản lý endpoint webhook, secret, sự kiện test và việc gửi lại. |

Key mới bắt đầu với năm scope đọc: `members:read`, `catalog:read`, `earnings:read`, `payouts:read` và `links:read`. Các scope ghi, DDEX và webhook không bao giờ được bật mặc định.

Hãy cấp cho mỗi hệ thống một key riêng, chỉ với những scope nó cần. Một job báo cáo cần `earnings:read`, không cần `ddex:write`. Một job CI kiểm tra tệp DDEX chỉ cần `ddex:validate`.

## Xoay vòng key

Key không được xoay vòng tại chỗ. Để thay một key mà không gián đoạn dịch vụ:

1. Tạo một key mới với cùng các scope.
2. Triển khai key mới lên hệ thống của bạn.
3. Kiểm tra lưu lượng đã chuyển sang key mới. Danh sách key cho biết lần cuối mỗi key được dùng.
4. Thu hồi key cũ.

## Thu hồi key

Trên trang **Developers**, mở menu của key và chọn **Revoke**. Key ngừng hoạt động ngay lập tức và trả về `401 key_revoked`. Hãy thu hồi key ngay nếu nó bị lộ, ví dụ khi đã bị commit lên repository hoặc dán vào một cuộc trò chuyện.

Mỗi key còn có nhật ký request. Chọn một key trong danh sách để xem các request gần đây: method, đường dẫn, mã trạng thái và thời gian. Request được lưu 7 ngày.

## Lỗi xác thực

| Mã trạng thái | `code` | Cần làm gì |
| --- | --- | --- |
| 401 | `unauthenticated` | Không có header `Authorization: Bearer`. Hãy thêm vào. |
| 401 | `invalid_key` | Key không tồn tại hoặc bị gõ sai. Kiểm tra khoảng trắng hoặc giá trị bị cắt mất. |
| 401 | `key_revoked` | Key đã bị thu hồi. Hãy tạo key mới. |
| 401 | `key_expired` | Key đã quá hạn. Hãy tạo key mới. |
| 401 | `test_keys_retired` | Một key `hm_test_` cũ. Hãy dùng key `hm_live_`. |
| 403 | `insufficient_scope` | Key thiếu scope được nêu trong `scope`. Hãy tạo key có scope đó. |
| 403 | `account_inactive` | Tài khoản của bạn không hoạt động. Liên hệ HILLS Music. |
| 403 | `api_not_in_plan` | Gói của bạn không bao gồm API. API đi kèm Enterprise và Custom. |

Mọi lỗi đều có cùng một cấu trúc. Xem [Lỗi](https://developer.hillsmusic.com/vi/guides/errors/).

## Giữ key an toàn

- Lưu key trong trình quản lý secret hoặc biến môi trường, không lưu trong code.
- Không bao giờ đặt key trong trang web, ứng dụng di động hay ứng dụng desktop. Ở đó ai cũng đọc được.
- Mỗi hệ thống dùng một key, để bạn có thể thu hồi một key mà không làm dừng các hệ thống khác.
- Đặt thời hạn cho key dùng trong dự án ngắn hạn hoặc cấp cho nhà thầu.

Nguồn: https://developer.hillsmusic.com/vi/guides/authentication/