# API-ключі AfterPack

Створення, обмеження, використання та відкликання ключа, який перетворює локальну збірку на збірку Pro Cloud.

Source: https://www.afterpack.dev/uk/docs/dashboard/api-keys

API-ключ перетворює локальну збірку на збірку **Pro Cloud**. Без нього [`npx afterpack@latest`](https://www.afterpack.dev/uk/docs/cli#usage) і кожен [плагін](https://www.afterpack.dev/uk/docs/frameworks) працюють локально із захистом рівня [Free](https://www.afterpack.dev/uk/docs/tiers) і нічого не звітують. З ним файли збірки надходять до хмарного рушія AfterPack, обліковуються у вашому робочому просторі та фіксуються в дашборді.

## Де зберігаються ключі

Ключі належать **проєкту** і розташовані на його сторінці *API-ключі*: ключ прив'язаний до одного проєкту, а його збірки успадковують цей проєкт, тож [збірки](https://www.afterpack.dev/uk/docs/dashboard/builds), [Protection Map](https://www.afterpack.dev/uk/docs/protection-map) і [використання](https://www.afterpack.dev/uk/docs/dashboard/usage) групуються під ним. У всьому іншому ключ є обліковими даними рівня робочого простору: він витрачає ліміт робочого простору, а доступ до нього визначає [роль у робочому просторі](https://www.afterpack.dev/uk/docs/dashboard/workspaces).

## Створення ключа

Створювати ключі можуть лише власники та адміністратори робочого простору і лише з дашборду. Ключ не може створити інший ключ. Діалог створення запитує:

- **Назва** (обов'язково, до 100 символів): для чого ключ, наприклад *CI-конвеєр*. Пізніше це єдине, що відрізняє рядки, тож називайте ключ за тим, де він зберігатиметься.
- **Термін дії до** (необов'язково, у *додаткових параметрах*): дата, що відраховується до кінця дня за місцевим часом. Дата в минулому повертає помилку.
- **Дозволені IP** (необов'язково, у *додаткових параметрах*): список через кому, наприклад `10.0.0.0/8, 203.0.113.7`.

> **Ключ показується рівно один раз**
>
> Сирий ключ повертається один раз і ніколи не зберігається; зберігаються лише хеш і короткий несекретний префікс. Скопіюйте його, перш ніж закрити діалог. Якщо ви його загубили, відкличте його і створіть інший. Показати його знову неможливо.

Ключі мають вигляд `ap_v1_`, за яким іде 40 випадкових символів base62, а список показує лише збережений префікс (`ap_v1_` плюс шість символів) із `*`. Ключ прив'язує збірки до свого проєкту, але не обмежує, на який проєкт може бути спрямована збірка. [`scope.allowedProjects`](https://www.afterpack.dev/uk/docs/cloud-api) повертає помилку.

## Використання ключа

Рушій шукає [`key`](https://www.afterpack.dev/uk/docs/config#key) спершу в `--key=`, потім у змінних середовища, потім в `afterpack.json`. Задайте [`AFTERPACK_key`](https://www.afterpack.dev/uk/docs/config#key) як секрет у [CI](https://www.afterpack.dev/uk/docs/builds) або покладіть його в `afterpack.json` для локальної проби:

```json
{ "key": "ap_v1_..." }
```

Якщо ключа немає ні там, ні там, збірка виконується локально: це поведінка за замовчуванням і весь шлях [тарифу Free](https://www.afterpack.dev/uk/docs/deployment-modes).

> **Ключу місце в CI, а не в репозиторії**
>
> `afterpack.json` підходить для локального пробного запуску, але, закомітивши його, ви публікуєте облікові дані, які витрачають ліміт вашого робочого простору. Для всього спільного використовуйте [`AFTERPACK_key`](https://www.afterpack.dev/uk/docs/config#key). Див. [Збірки та CI](https://www.afterpack.dev/uk/docs/builds).

## Список ключів

| Стовпець | Що це |
| --- | --- |
| **Назва** | Як ви його назвали. |
| **Ключ** | Збережений префікс для показу, `ap_v1_xxxxxx*`. |
| **Створено** | Коли його створено. |
| **Закінчується** | Дата закінчення терміну дії або *Ніколи*. |
| **Останнє використання** | Коли збірка востаннє автентифікувалася ним; корисно, щоб знайти ключ, яким уже ніщо не користується. |
| **Статус** | *Активний* або *Відкликано*. |

## Ротація

Ротації на місці немає. Ротація завжди означає **створити новий, потім відкликати старий**, а оскільки ключ сам по собі ніколи не закінчується, якщо ви не задали термін під час створення, обидва можуть діяти одночасно стільки, скільки триває розгортання:

1. Створіть новий ключ.
2. Розгорніть його всюди, де використовувався старий (секрети CI, конфігурації розгортання).
3. Переконайтеся за стовпцем **Останнє використання**, що збірки автентифікуються новим ключем.
4. Відкличте старий.

## Відкликання

Відкликання діє негайно і його неможливо скасувати: ключ перестає працювати з наступного запиту. Рядок залишається видимим із позначкою *Відкликано*, а не зникає, тож ви можете побачити, для чого ключ використовувався. Відкликати ключ може його автор, а також будь-який адміністратор чи власник його робочого простору, тож ключ, створений людиною, яка відтоді пішла, усе одно можна відкликати. Відкликання є дією в дашборді: API-ключ не може відкликати ключ, зокрема й сам себе. Якщо ключ відкликано посеред збірки, наступний запит CLI з ним завершиться помилкою.

> **Якщо ключ витік, відкличте його**
>
> Відкликання набуває чинності глобально за лічені секунди і є повним виправленням: AfterPack ніколи не зберігає сирий ключ після створення, лише непрозорий ідентифікатор, несекретний префікс і солений хеш, тож потім не потрібно чистити жоден кеш чи журнал. Якщо ви не можете зайти в дашборд, напишіть на **security@afterpack.dev**.

## Обмеження для збірки з ключем

| | Обмеження |
| --- | --- |
| Запитів на ключ за хвилину | 10 на Free, 100 на платному плані |
| Запитів з однієї IP за хвилину | 100 |
| Байтів на файл | 50 MB |
| Файлів у пакеті | 200 |
| Байтів у пакеті | 500 MB |

Збірка, що перевищує обмеження, [завершується помилкою](https://www.afterpack.dev/uk/docs/diagnostics#exit-codes), а не переходить до необфускованого результату. Протокол і коди помилок описано в розділі [Cloud API](https://www.afterpack.dev/uk/docs/cloud-api).

## Коли збірки не з'являються

Майже завжди причина одна з цих:

1. **Ключ не знайдено**: збірка виконалася локально. Перевірте, що [`AFTERPACK_key`](https://www.afterpack.dev/uk/docs/config#key) задано там, де виконується збірка.
2. **Ключ відкликано або його термін дії минув**: список показує, що саме.
3. **Ви дивитеся не на той проєкт**: збірку прив'язано до проєкту ключа, який може відрізнятися від відкритого у вас.

## Далі

- [Збірки](https://www.afterpack.dev/uk/docs/dashboard/builds): що створює збірка з ключем.
- [Використання та оплата](https://www.afterpack.dev/uk/docs/dashboard/usage): скільки це коштує.
- [Cloud API](https://www.afterpack.dev/uk/docs/cloud-api): протокол, у якому автентифікується ключ.
- [Робочі простори та проєкти](https://www.afterpack.dev/uk/docs/dashboard/workspaces): ролі, що визначають доступ до цієї сторінки.