Аутентификация

Каждый вызов /api/v1 требует учётных данных, кроме общедоступных проверок работоспособности, параметров входа, входа и регистрации. На этой странице перечислены виды учётных данных, способы получить и отправить каждый из них и смысл правил доступа в справочнике API. Правила для тех, кто управляет доступом, описаны на странице Учётные записи и доступ.

Учётные данные вкратце

Учётные данные	Как выглядят	Как получить	Срок действия	Для чего
Сессия консоли	dps_…	Вход по имени и паролю	12 часов	Человек в консоли или скрипт, который входит сам
Персональный токен доступа	pat_…	Создаётся из сессии	По умолчанию 90 дней, не более 365	Скрипты и инструменты одного человека
Ключ сервиса	arkvory_…	Выпускается для сервисной учётной записи, затем активируется	По умолчанию 90 дней, не более 365	CI/CD, агенты развёртывания, другие системы
Ключ восстановления	64 шестнадцатеричные цифры	Установщик записывает его в config/bootstrap-token.txt	Не истекает	Создание владельца, администрирование сервисных учётных записей, восстановление доступа
Ссылка на скачивание	dtl_…	Создаётся для одного артефакта	От 60 секунд до 24 часов	Передача одного артефакта тому, у кого нет ключа

Для автоматизации используйте ключ сервиса, а для инструментов человека — персональный токен доступа. Не используйте ключ восстановления в повседневной работе.

Форматы заголовков

/api/v1 принимает учётные данные в одном заголовке:

Authorization: Bearer <ключ>

• Учётные данные содержат от 32 до 512 символов. Всё остальное сразу получает credential_invalid.
• Реестр контейнеров (/v2), Git LFS (/lfs) и реестр npm (/npm) также принимают HTTP Basic, потому что docker login, git и npm передают учётные данные именно так. Имя пользователя не проверяется; паролем служат учётные данные. См. Клиенты и протоколы.
• Ссылка на скачивание передаётся в строке запроса как ?token=dtl_… и работает только на маршруте содержимого одного артефакта. См. Ссылки на скачивание. Заголовок Authorization всегда главнее строки запроса.
• Запрос без действительных учётных данных получает 401 с WWW-Authenticate: Bearer и причиной: credential_missing, credential_invalid, session_expired или token_expired. Только тот, у кого есть точный секрет истёкших учётных данных, узнаёт, что они истекли.
• Без cookie. Arkvory не устанавливает и не читает cookie, поэтому браузер никогда не прикладывает учётные данные сам и защищаться от межсайтовой подделки запросов (CSRF) не нужно. Скрипт отправляет заголовок в каждом вызове. Консоль хранит токен сессии в памяти вкладки браузера и забывает его, когда вы закрываете вкладку.
• Другие источники. Странице на том же адресе, что и Arkvory, ничего не нужно. Страница на другом адресе получает 403 с причиной origin_not_allowed, если администратор не перечислил её источник в ARKVORY_CORS_ORIGINS, даже при действительных учётных данных. Используйте HTTPS: учётные данные в обычном HTTP можно прочитать в сети. См. HTTPS.

Проверьте, что это за учётные данные и что им разрешено:

curl -fsS -H "Authorization: Bearer $ARKVORY_KEY" "$ARKVORY_URL/api/v1/auth/me"
curl -fsS -H "Authorization: Bearer $ARKVORY_KEY" "$ARKVORY_URL/api/v1/auth/permissions"

Сессии входа в консоль

Человек входит по имени и паролю и получает сессию. Консоль делает это за вас; скрипт может сделать то же самое.

1. Поместите имя и пароль в закрытый файл login.json, чтобы они никогда не попадали в командную строку или список процессов:

   { "name": "alice", "password": "a long password of 12 to 128 characters" }

2. Вызовите login:

   curl -fsS -X POST "$ARKVORY_URL/api/v1/auth/login" \
     -H "Content-Type: application/json" -d @login.json

3. В ответе — токен сессии и время её окончания:

   {
     "token": "dps_…",
     "expiresAt": "2026-10-05T21:30:00.000Z",
     "account": { "id": "…", "name": "alice", "administrator": false, "enabled": true }
   }

4. Отправляйте токен как Authorization: Bearer dps_….

Правила сессии:

• Сессия длится 12 часов и не продлевается. После этого каждый вызов возвращает 401 с причиной session_expired. Войдите снова.
• У учётной записи не более 32 сессий. Новый вход завершает самые старые сверх этого числа.
• POST /api/v1/auth/logout завершает сессию. Смена пароля или его сброс администратором завершает все сессии и все персональные токены учётной записи. Отключение учётной записи останавливает их.
• Сессия несёт все полномочия учётной записи, включая признак администратора. Только сессия может создавать и отзывать персональные токены и менять пароль самой учётной записи.
• Имена сравниваются без учёта регистра. Неверное имя, неверный пароль и отключённая учётная запись дают один и тот же 401 с причиной invalid_credentials.
• Шлюз чтения никого не впускает; используйте узел записи.

Самостоятельная регистрация

GET /api/v1/auth/options общедоступен и сообщает, могут ли люди создавать собственные учётные записи. Самостоятельная регистрация выключена, пока администратор не задаст ARKVORY_ALLOW_REGISTRATION=true; тогда POST /api/v1/auth/register с тем же телом, что и вход, создаёт обычную учётную запись (не администратора, без доступа к какому-либо репозиторию) и возвращает сессию с кодом 201. Иначе он отвечает 403 с причиной registration_disabled. Самостоятельная регистрация прекращается на 900 учётных записях, чтобы администраторы могли создавать учётные записи вплоть до предела в 1000.

Персональные токены доступа

Персональный токен доступа позволяет скрипту действовать от вашего имени без вашего пароля. Создать его может только вошедшая сессия.

curl -fsS -X POST "$ARKVORY_URL/api/v1/auth/tokens" \
  -H "Authorization: Bearer $SESSION" -H "Content-Type: application/json" \
  -d '{"name":"laptop-cli","scope":"read-write","expiresAt":"2026-12-31T00:00:00Z"}'

В консоли откройте Персональные токены доступа в карточке Подключение к репозиторию, заполните поле Название токена, выберите значения в полях Доступ и Срок действия и нажмите Создать токен.

Поле	Правило
name	От 1 до 64 символов.
scope	read или read-write. API использует read-write, если поле не указано; консоль сначала предлагает Только чтение.
expiresAt	Время RFC 3339 в будущем, не позже чем через 365 дней. По умолчанию — 90 дней. Токенов без срока окончания не бывает.

Ответ 201 содержит токен один раз, в поле token. Сохраните его сразу: сервер хранит только хеш, а в списке показан короткий префикс. Далее:

• У токена есть доступ к репозиториям его учётной записи и ничего сверх этого. У него никогда нет признака администратора, поэтому он не может управлять учётными записями, группами, обновлениями или резервными копиями.
• Токен read может только читать. Любой запрос, который что-то меняет, кроме logout, отклоняется с 403 и причиной read_only_token до выполнения операции.
• Токен не может создавать токены или менять пароль; для этого нужна сессия.
• У учётной записи не более 50 действующих токенов. GET /api/v1/auth/tokens перечисляет их с префиксом, областью доступа, сроком окончания и временем последнего использования. DELETE /api/v1/auth/tokens/{id} сразу отзывает токен (Отозвать токен в консоли). Администратор может перечислять и отзывать токены любой учётной записи.
• Истёкший токен возвращает 401 с причиной token_expired.

Сервисные учётные записи и ключи

Сервисная учётная запись — это идентичность для инструмента, например агента сборки. У неё есть политика: список привязок, каждая из которых называет один репозиторий и точные действия, разрешённые на нём (см. Действия над репозиториями). В политике не более 64 привязок. Учётная запись владеет загрузками и заданиями, которые начинают её ключи, поэтому ротация ключа ничего не теряет. На сервере не более 1000 сервисных учётных записей.

Сервисную учётную запись создаёт только ключ восстановления. Он, либо оператор с делегированием, меняет существующие учётные записи. В консоли откройте раздел Сервисный доступ: нажмите Создать сервисный аккаунт, затем задайте Права на репозитории. Набор для чтения заполняет семь действий чтения, а Набор для публикации добавляет действия, нужные для загрузки и регистрации пакетов.

curl -fsS -X POST "$ARKVORY_URL/api/v1/service-accounts" \
  -H "Authorization: Bearer $RECOVERY_KEY" -H "Content-Type: application/json" \
  -d '{"name":"ci-release","bindings":[{"resource":{"kind":"repository","id":"releases"},
       "actions":["repository.read","artifact.read","upload.create","upload.read","upload.write",
                  "upload.complete","upload.cancel","job.read","package.publish"]}]}'

Имена состоят из 3–64 букв, цифр, _, . и -. Чтобы изменить политику, отправьте PUT /api/v1/service-accounts/{id}/policy с прочитанным вами expectedRevision (compare-and-swap). Чтобы отключить учётную запись, отправьте PATCH /api/v1/service-accounts/{id} с {"expectedRevision": n, "enabled": false}; все её ключи перестают работать, пока вы не включите её снова.

Ключи сервиса

Ключ — это секрет, с которым входит сервисная учётная запись. Он выглядит как arkvory_<uuid>.<секрет>. Ключ проходит три состояния: pending, active и revoked.

1. Выпуск. Отправьте POST /api/v1/service-accounts/{id}/keys с Idempotency-Key, name, bindings, которые может использовать ключ, и, если нужно, expiresAt (UTC, не позже чем через 365 дней; по умолчанию — 90). Привязки ключа должны лежать в пределах политики учётной записи. Ответ 201 содержит метаданные ключа и, только один раз, его secret. Повтор с тем же ключом идемпотентности возвращает 200 с метаданными и без секрета.
2. Активация. Новый ключ находится в состоянии pending и непригоден ни для чего, кроме одного вызова — POST /api/v1/auth/activate-key, где учётными данными служит новый секрет. Ответ — 204. Сделайте это в течение 15 минут; после этого неиспользованный ключ истекает. В консоли скопируйте секрет, подтвердите Секрет сохранён и нажмите Активировать ключ. Повторная активация безвредна.
3. Использование. Ключ работает до expiresAt либо пока его не отозвали или пока не отключена его учётная запись.

curl -fsS -X POST "$ARKVORY_URL/api/v1/service-accounts/$ACCOUNT/keys" \
  -H "Authorization: Bearer $RECOVERY_KEY" -H "Idempotency-Key: ci-release-2026-10" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-release-2026-10","bindings":[{"resource":{"kind":"repository","id":"releases"},
       "actions":["upload.create","upload.read","upload.write","upload.complete","job.read"]}]}'
curl -fsS -X POST "$ARKVORY_URL/api/v1/auth/activate-key" -H "Authorization: Bearer $NEW_SECRET"

Ограничения: у учётной записи одновременно не более 3 действующих и 2 ожидающих ключей (507 с причиной key_limit).

Ротация. POST /api/v1/api-keys/{id}/rotate выпускает новый ожидающий ключ для той же учётной записи, с тем же телом, что и при выпуске, и с Idempotency-Key. Его привязки должны лежать в пределах привязок старого ключа. Когда вы активируете новый ключ, срок действия старого сокращается не более чем до 24 часов с этого момента. Переведите свои инструменты на новый ключ, затем отзовите старый. В консоли: Ротировать.

Отзыв. POST /api/v1/api-keys/{id}/revoke навсегда завершает действие ключа; повторный вызов безвреден. В консоли: Отозвать. Отзыв ключа не останавливает передачу, которая уже началась. Потеряли секрет ожидающего ключа? Отзовите его и выпустите другой с новым ключом идемпотентности.

Делегирование

Ключ восстановления может передать часть администрирования оператору — сервисной учётной записи, ключ которой может управлять другими сервисными учётными записями. Делегирование называет ключ оператора, целевую учётную запись, действия администрирования, которые оператор может использовать на ней, и потолок — действия над репозиториями, которые он может выдавать. Семь действий администрирования:

Действие	Что разрешает
service-account.read	Видеть учётную запись в списках и читать её карточку.
service-account.manage	Включать и отключать учётную запись.
policy.read	Читать политику учётной записи.
policy.manage	Заменять политику учётной записи.
credential.read	Перечислять ключи учётной записи и читать ключ.
credential.manage	Выпускать, ротировать и отзывать ключи.
service-audit.read	Читать историю ключей учётной записи.

Правила: ключ оператора должен быть выпущен ключом восстановления; оператор никогда не управляет собственной учётной записью; он не может выдать ничего сверх своего потолка или сверх политики учётной записи; выпущенный им ключ не может пережить его собственный ключ; а завершение делегирования не отзывает уже активированные ключи. Только ключ восстановления создаёт учётные записи и задаёт делегирование (PUT и DELETE /api/v1/api-keys/{id}/delegations/{accountId}). У одного ключа оператора может быть до 64 делегирований. В консоли откройте Делегирование управления. Оператор, которому нужно что-то сверх его делегирования, получает 404 для учётной записи, которой он не управляет, либо 403.

Ключ восстановления

Установщик создаёт ключ восстановления один раз и записывает его в config/bootstrap-token.txt в корне установки. Прочитать файл может только группа «Администраторы» в Windows или root в Linux. Его хеш находится в файле ключей сервера (ARKVORY_KEYS_FILE) под именем bootstrap-owner. Установщик также создаёт config/health-token.txt — второй ключ без каких-либо прав на репозитории, который может вызывать проверки работоспособности с аутентификацией и метрики.

Что может ключ восстановления:

• Создавать первую и каждую следующую учётную запись, сбрасывать пароли, отключать учётные записи и управлять группами и их доступом к репозиториям.
• Читать журнал безопасности и отзывать персональные токены любой учётной записи.
• Создавать сервисные учётные записи, задавать их политики, выпускать и отзывать их ключи и задавать делегирование.
• Читать и запрашивать резервные копии и обновления и скачивать журнал сервера для обратной связи.
• Читать и записывать репозиторий releases, как участник группы с доступом Чтение и запись.

Чего он не может: у него нет доступа к репозиториям, кроме releases, он не может удалять артефакты и управлять политиками хранения (эти действия существуют только для ключей сервиса) и не является сессией, поэтому не может создавать персональные токены или менять пароль. Храните его на сервере. Средства установки читают его там. Не помещайте его в CI и не вставляйте в инструменты; вместо этого создайте ключ сервиса. Чтобы заменить его, см. Настройка.

Форма Создать первого владельца в консоли (в разделе Начало работы) использует ключ восстановления, чтобы создать первого владельца. Она работает, только пока нет ни одной учётной записи. Чтобы сбросить пароль существующей учётной записи без сессии, найдите её ID через GET /api/v1/users, поместите новый пароль (12–128 символов) в закрытый файл и отправьте его с ключом восстановления. Сброс завершает все сессии и токены этой учётной записи.

echo '{"password": "a new password of 12 to 128 characters"}' > reset.json
curl -fsS -X PATCH "$ARKVORY_URL/api/v1/users/$USER_ID" \
  -H "Authorization: Bearer $RECOVERY_KEY" -H "Content-Type: application/json" -d @reset.json
rm reset.json

Другие файловые ключи администратор может добавить в файл ключей. Каждая запись содержит id, sha256 секрета, repositories и permissions (read и write), которые она даёт, и, по желанию, флаги administrator и serviceAdministrator. Файл читается при запуске, поэтому после изменения перезапустите API и обработчик.

Ссылки на скачивание

POST /api/v1/repositories/{repository}/artifacts/{id}/links возвращает token (dtl_…) и url для одного артефакта. Срок действия задаётся в ttlSeconds: от 60 до 86 400, по умолчанию 3600. Вызывающему нужно content.read.

Ссылка работает только как GET или HEAD для /api/v1/repositories/{repository}/artifacts/{id}/content?token=…, для этого артефакта в этом репозитории и только для чтения. Это секрет. Сервер не может отозвать её до истечения срока, и она не попадает в журналы. Создавайте ссылки с наименьшим нужным вам сроком.

Что значит правило доступа

У каждой операции в справочнике есть строка Доступ. Вот виды правил:

Правило в справочнике	Что требуется
Любой, без ключа	Ничего. Проверка живости, статус готовности, параметры входа, вход и регистрация.
Любой действующий ключ или сессия	Любые действительные учётные данные. Примеры: возможности, список операций, сведения о себе, подробности готовности и метрики.
Сессия учётной записи (не ключ)	Сессия человека. Персональные токены и ключи отклоняются (session_required). Примеры: создание и отзыв собственных токенов, смена пароля.
Администратор	Сессия учётной записи администратора или файловый ключ с признаком администратора, например ключ восстановления. Персональные токены и ключи сервиса отклоняются (administrator_required). Примеры: учётные записи, группы, журнал безопасности, обновления.
Ключ установки (ключ восстановления)	Файловый ключ с признаком администрирования сервисов. Он есть у ключа восстановления. Примеры: создание сервисных учётных записей и задание делегирования.
Ключ установки или сам этот ключ	Ключ восстановления или ключ, чьи делегирования перечисляются.
Выданный ключ до или после активации	Единственная операция, которая принимает ожидающий ключ: активация.
Репозитории, которые видит вызывающий	Действие repository.read в этом репозитории или любой доступ к нему для сессии или файлового ключа. Репозиторий, которого вызывающий не видит, отсутствует в списках и отвечает 404.
Системное право backup.read или backup.manage	Есть у сессий администраторов и у файловых ключей с признаком администратора. У ключей сервиса и персональных токенов их никогда нет. backup.manage включает backup.read.
Право администрирования сервисов	Одно из семи действий администрирования на целевой учётной записи — из делегирования либо у ключа восстановления.
Право в репозитории	Все перечисленные действия над репозиторием, названным в пути. Несколько правил доступа добавляют условия: загрузка, задание или ссылка должны принадлежать вызывающему.

Вторая часть строки про репозиторий, например «файловые ключи: read, write», — это общий доступ, который нужен людям и файловым ключам вместо точных действий. См. Групповой доступ.

Помимо правила доступа сервер также отклоняет изменение в репозитории, который является зеркалом (409, mirror_read_only), а шлюз чтения отклоняет любое изменение (405, read_only).

Права на репозитории

Групповой доступ

Люди получают доступ к репозиториям через группы. Администратор выдаёт группе read или write (в консоли — «Чтение и запись») на репозиторий и добавляет в группу учётные записи. В консоли откройте Пользователи и доступ, затем Доступ к репозиториям и нажмите Сохранить доступ. Вызовы API: PUT /api/v1/access-groups/{id}/grants/{repository} с {"access": "read"} или {"access": "write"} и PUT /api/v1/access-groups/{id}/members/{userId}. Права пересчитываются при каждом запросе, поэтому изменение действует сразу.

Доступ read даёт такие действия: repository.read, artifact.read, artifact.list, content.read, package.read, asset.read и annotation.read. Доступ write добавляет upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.publish, asset.write, asset.restore, annotation.write, reference.write, artifact.promote и audit.read. Действия artifact.delete, storage.read, storage.manage и diagnostics.read не могут прийти от группы: их может иметь только ключ сервиса.

Действия над репозиториями

Ключ сервиса несёт точные действия по каждому репозиторию. Их 24:

Действие	Что разрешает
repository.read	Видеть репозиторий и состояние его зеркала.
artifact.read	Читать свойства артефакта, его стадии и продвижения. Также нужно при любом изменении артефакта.
artifact.list	Перечислять и искать артефакты, перечислять артефакты по стадиям, читать журнал продвижений и ленту изменений.
artifact.promote	Ставить и снимать стадии и продвигать (копировать или переносить) в другой репозиторий.
artifact.delete	Удалять артефакты, просматривать результат и применять правила хранения, удалять образы контейнеров и принудительно снимать блокировки файлов Git LFS.
content.read	Скачивать байты по ID, по пакету или по пути и создавать ссылки на скачивание.
upload.create	Создавать сессии загрузки. Её используют push в реестры и Git LFS.
upload.read	Читать собственные сессии загрузки и их части.
upload.write	Отправлять части или всё содержимое собственной загрузки.
upload.complete	Завершать собственную загрузку или ставить её завершение в очередь.
upload.cancel	Отменять собственную ожидающую загрузку.
job.read	Читать собственные задания завершения.
package.read	Перечислять пакеты, находить версии и скачивать пакеты.
package.publish	Регистрировать архив UPack как пакет.
asset.read	Перечислять файлы по пути и читать их указатели, историю и версии. Для скачивания байтов нужно content.read.
asset.write	Направлять путь на артефакт или сохранять обычный файл.
asset.restore	Восстанавливать прежнюю версию пути.
annotation.read	Читать метки, метаданные, коллекции и вложения.
annotation.write	Заменять метки, метаданные, коллекции и вложения.
reference.write	Добавлять и удалять ссылки удержания, которые защищают артефакт.
audit.read	Читать журнал аудита каталога репозитория.
storage.read	Читать квоту, занятое место, политику хранения и настройки очистки.
storage.manage	Менять политику хранения и настройки очистки и запускать очистку.
diagnostics.read	Читать события хранилища.

Точный набор, который нужен операции, указан в её строке в справочнике, например upload.write и upload.complete для putUploadContent. Для изменения в репозитории нужно и соответствующее действие чтения, например artifact.read вместе с annotation.write.

Условия владельца применяются к загрузкам и заданиям: вы действуете только с теми сессиями загрузки и заданиями завершения, которые создала ваша учётная запись. Все ключи одной сервисной учётной записи и все сессии и токены одного человека считаются одним владельцем. Поэтому несколько сервисов в одном репозитории разделяются учётными записями и репозиториями, а не префиксами пути.

Права администрирования и системные права

Ещё два вида прав не являются действиями над репозиториями. Семь действий администрирования перечислены в разделе Делегирование. Два системных права, backup.read и backup.manage, принадлежат только администраторам и ключу восстановления.

Ограничения входа

Сервер замедляет подбор пароля раньше, чем проверит какой-либо пароль. Счётчики хранятся в памяти каждого процесса API и начинаются заново после перезапуска. Они действуют для каждого адреса клиента, а адрес IPv6 считается по префиксу /64. За обратным прокси-сервером задайте ARKVORY_TRUSTED_PROXIES, иначе каждый клиент будет выглядеть как прокси.

Ограничение	Значение
Попытки входа на адрес	Всплеск из 10, затем ещё одна каждые 15 секунд. Успешный вход попытку не расходует.
Неверные пароли на учётную запись	Каждый неверный пароль добавляет 1 к долгу, который уменьшается на 1 каждые 6 секунд. Выше 20 учётная запись отклоняет попытки на 1 секунду, удваивая срок при каждой следующей неудаче, максимум до 2 минут; в это время даже верный пароль получает 429. Успешный вход или сброс обнуляют долг.
Регистрации на адрес	3, затем ещё одна каждые 20 минут.
Регистрации на сервер	20, затем ещё одна каждые 3 минуты.
Запросы входа в обработке	16 на процесс API, тело должно прийти за 10 секунд. Сверх этого — 503 с кодом busy.

Отклонённая попытка возвращает 429 с кодом rate_limited, причиной login_attempts, registration_attempts или password_attempts и Retry-After в секундах. Подождите это время; не повторяйте в цикле. Для смены и сброса пароля действует собственный предел с причиной password_attempts. Все входы, регистрации, смены пароля и изменения токенов записываются в журнал безопасности (GET /api/v1/security/audit, только для администраторов), который хранится 365 дней.

Связанные страницы

• Обзор API
• Ошибки
• Учётные записи и доступ
• Безопасность
• Клиенты и протоколы
• Справочник: Учётные записи и вход, Сервисные аккаунты и ключи