Учётные записи и вход
Вход, сессии, персональные токены, пользователи, группы и журнал безопасности.
Операции этой группы с правилом доступа, правилом повтора, параметрами и ответами. Каждый запрос несёт ключ: Authorization: Bearer <ключ> (см. «Аутентификация»).
Операции
Войти
POST /api/v1/auth/login
Доступ: Любой, без ключа · Повтор: Не повторять автоматически
Обменивает name и password учётной записи на сессионный токен token типа bearer, действующий 12 часов, с expiresAt и учётной записью; передавайте его как Authorization: Bearer. Неизвестное имя, неверный пароль и отключённая учётная запись дают один и тот же ответ 401 invalid_credentials. Попытки ограничиваются по адресу клиента и по учётной записи (429 rate_limited с Retry-After), а у учётной записи не более 32 сессий: новая завершает самую старую.
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
name | string | да | — |
password | string (password) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
token | string | да | — |
expiresAt | string (date-time) | да | — |
account | object | да | — |
account.id | string (uuid) | да | — |
account.name | string | да | — |
account.administrator | boolean | да | — |
account.enabled | boolean | да | — |
Ответы: 200, 400, 401, 403, 405, 413, 415, 429, 503
Пример
curl -X POST "$ARKVORY_URL/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","password":"<password>"}'Зарегистрировать учётную запись
POST /api/v1/auth/register
Доступ: Любой, без ключа · Повтор: Не повторять автоматически
Создаёт обычную учётную запись (не администратора) с name (3–64 символа: буквы, цифры или _.-) и password (12–128 символов) и выполняет вход, отвечая 201 с 12-часовой сессией, как login. Работает, только если сервер разрешает саморегистрацию (см. getAuthOptions), иначе 403 registration_disabled; занятое имя — 409 already_exists. Попытки ограничиваются по адресу клиента (429 с Retry-After), а саморегистрация прекращается при 900 учётных записях.
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
name | string | да | — |
password | string (password) | да | — |
Ответ 201
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
token | string | да | — |
expiresAt | string (date-time) | да | — |
account | object | да | — |
account.id | string (uuid) | да | — |
account.name | string | да | — |
account.administrator | boolean | да | — |
account.enabled | boolean | да | — |
Ответы: 201, 400, 403, 405, 413, 415, 429, 503
Пример
curl -X POST "$ARKVORY_URL/api/v1/auth/register" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","password":"<password>"}'Получить параметры входа
GET HEAD /api/v1/auth/options
Доступ: Любой, без ключа · Повтор: Можно повторять (чтение)
Сообщает консоли до входа, какие формы показывать: selfRegistration равно true, когда на этом сервере открыт registerAccount.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
selfRegistration | boolean | да | — |
Ответы: 200, 400, 403, 503
Пример
curl -X GET "$ARKVORY_URL/api/v1/auth/options"Перечислить ваши персональные токены доступа
GET HEAD /api/v1/auth/tokens
Доступ: Сессия учётной записи (не ключ) · Повтор: Можно повторять (чтение)
Перечисляет персональные токены доступа текущей учётной записи, сначала действующие, с именем, префиксом, областью доступа, временем создания, сроком действия, последним использованием и признаком отзыва; секреты больше не показываются.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].id | string (uuid) | да | — |
items[].name | string | да | — |
items[].prefix | string | да | — |
items[].scope | string | да | одно из read, read-write |
items[].createdAt | string (date-time) | да | — |
items[].expiresAt | string (date-time) | нет | может быть null |
items[].lastUsedAt | string (date-time) | нет | может быть null |
items[].revoked | boolean | да | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/auth/tokens" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Создать персональный токен доступа
POST /api/v1/auth/tokens
Доступ: Сессия учётной записи (не ключ) · Повтор: Не повторять автоматически
Создаёт токен для скриптов и инструментов, который действует от имени текущей учётной записи; секрет есть только в этом ответе. name — 1–64 символа, expiresAt по умолчанию через 90 суток, должен быть в будущем и не позднее чем через 365 суток, scope — read-write (по умолчанию) или read, который никогда ничего не изменяет. Токены никогда не дают прав администратора и не могут создавать токены, а у учётной записи может быть не более 50 действующих (507 token_limit).
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
name | string | да | — |
expiresAt | string (date-time) | нет | — |
scope | string | нет | одно из read, read-write |
Ответ 201
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
name | string | да | — |
prefix | string | да | — |
scope | string | да | одно из read, read-write |
createdAt | string (date-time) | да | — |
expiresAt | string (date-time) | нет | может быть null |
lastUsedAt | string (date-time) | нет | может быть null |
revoked | boolean | да | — |
token | string | да | — |
Ответы: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/auth/tokens" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"<name>"}'Отозвать ваш персональный токен доступа
DELETE /api/v1/auth/tokens/{id}
Доступ: Сессия учётной записи (не ключ) · Повтор: Можно повторять: тот же запрос даёт тот же результат
Отзывает один персональный токен доступа текущей учётной записи; запросы с ним с этого момента завершаются ошибкой. Повторный отзыв уже отозванного токена тоже успешен.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/auth/tokens/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Выйти
POST /api/v1/auth/logout
Доступ: Любой действующий ключ или сессия · Повтор: Можно повторять: тот же запрос даёт тот же результат
Завершает сессию учётной записи, переданную в Authorization; её токен сразу перестаёт действовать. С любыми другими учётными данными (персональный токен или ключ сервиса) отвечает 204 и ничего не отзывает.
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/auth/logout" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Сменить свой пароль
POST /api/v1/auth/password
Доступ: Сессия учётной записи (не ключ) · Повтор: Не повторять автоматически
Устанавливает newPassword (12–128 символов) после проверки currentPassword; неверный текущий пароль даёт 401 current_password_invalid и учитывается в нарастающей задержке попыток входа. При успехе отзываются все сессии и все персональные токены доступа учётной записи, включая текущую сессию, поэтому войдите заново.
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
currentPassword | string (password) | да | — |
newPassword | string (password) | да | — |
Ответы: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 429, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/auth/password" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"currentPassword":"<currentPassword>","newPassword":"<newPassword>"}'Получить сведения о текущем вызывающем
GET HEAD /api/v1/auth/me
Доступ: Любой действующий ключ или сессия · Повтор: Можно повторять (чтение)
Возвращает, кому принадлежат учётные данные: их id, является ли владелец администратором, вид учётных данных (session, personal-token, service-key или file-key), область доступа персонального токена и репозитории, к которым есть доступ read или write. Используйте для показа вошедшего пользователя и выбора репозитория; точные права управляемого ключа сервиса возвращает getOwnPermissions.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string | да | — |
administrator | boolean | да | — |
credential | string | нет | одно из session, personal-token, service-key, file-key |
tokenScope | string | нет | одно из read, read-write |
grants | массив object | да | — |
grants[].repository | string | да | — |
grants[].permissions | массив string | да | каждый элемент: одно из read, write |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/auth/me" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Перечислить учётные записи
GET HEAD /api/v1/users
Доступ: Администратор · Повтор: Можно повторять (чтение)
Перечисляет все учётные записи пользователей в порядке имён, с ID, именем, признаком администратора и признаком, включены ли они. На сервере может быть не более 1000 учётных записей.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | нет | — |
items[].id | string (uuid) | да | — |
items[].name | string | да | — |
items[].administrator | boolean | да | — |
items[].enabled | boolean | да | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/users" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Создать учётную запись
POST /api/v1/users
Доступ: Администратор · Повтор: Не повторять автоматически
Создаёт учётную запись с name (3–64 символа: буквы, цифры или _.-), password (12–128 символов) и administrator (по умолчанию false) и отвечает 201 с ней. Занятое имя — 409 already_exists; на сервере может быть не более 1000 учётных записей (507 account_limit).
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
name | string | да | — |
password | string (password) | да | — |
administrator | boolean | нет | — |
Ответ 201
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
name | string | да | — |
administrator | boolean | да | — |
enabled | boolean | да | — |
Ответы: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/users" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","password":"<password>"}'Включить, отключить учётную запись или сбросить её пароль
PATCH /api/v1/users/{id}
Доступ: Администратор · Повтор: Не повторять автоматически
Меняет enabled и (или) задаёт новый password учётной записи; признак администратора здесь изменить нельзя. Отключение завершает все сессии учётной записи, а её персональные токены не работают, пока она отключена; сброс пароля завершает все сессии и отзывает все персональные токены.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
enabled | boolean | нет | — |
password | string (password) | нет | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
name | string | да | — |
administrator | boolean | да | — |
enabled | boolean | да | — |
Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X PATCH "$ARKVORY_URL/api/v1/users/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Перечислить персональные токены доступа учётной записи
GET HEAD /api/v1/users/{id}/tokens
Доступ: Администратор · Повтор: Можно повторять (чтение)
Перечисляет персональные токены доступа любой учётной записи, сначала действующие, с именем, префиксом, областью доступа, временем создания, сроком действия, последним использованием и признаком отзыва; секреты не показываются никогда. Используйте, чтобы проверить автоматизацию перед отключением или сбросом пароля учётной записи.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].id | string (uuid) | да | — |
items[].name | string | да | — |
items[].prefix | string | да | — |
items[].scope | string | да | одно из read, read-write |
items[].createdAt | string (date-time) | да | — |
items[].expiresAt | string (date-time) | нет | может быть null |
items[].lastUsedAt | string (date-time) | нет | может быть null |
items[].revoked | boolean | да | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/users/$ID/tokens" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Отозвать персональный токен доступа учётной записи
DELETE /api/v1/users/{id}/tokens/{tokenId}
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Отзывает один персональный токен доступа учётной записи id; запросы с ним с этого момента завершаются ошибкой, а событие записывается в аудит безопасности. Повторный отзыв уже отозванного токена тоже успешен.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
tokenId | путь | string (uuid) | да | — |
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/users/$ID/tokens/$TOKENID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Перечислить группы доступа
GET HEAD /api/v1/access-groups
Доступ: Администратор · Повтор: Можно повторять (чтение)
Перечисляет все группы доступа с ID учётных записей их участников и назначениями доступа к репозиториям (read или write). На сервере может быть не более 100 групп, 10 000 членств и 10 000 назначений доступа.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | нет | — |
items[].id | string (uuid) | да | — |
items[].name | string | да | — |
items[].members | массив string (uuid) | да | — |
items[].grants | массив object | да | — |
items[].grants[].repository | string | да | — |
items[].grants[].access | string | да | одно из read, write |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/access-groups" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Создать группу доступа
POST /api/v1/access-groups
Доступ: Администратор · Повтор: Не повторять автоматически
Создаёт пустую группу с name (2–64 символа: буквы, цифры или _.-) и отвечает 201 с ней; занятое имя — 409 already_exists. Добавляйте участников через addGroupMember, а репозитории — через setGroupGrant.
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
name | string | да | — |
Ответ 201
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
name | string | да | — |
members | массив string (uuid) | да | — |
grants | массив object | да | — |
grants[].repository | string | да | — |
grants[].access | string | да | одно из read, write |
Ответы: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/access-groups" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"<name>"}'Добавить учётную запись в группу
PUT /api/v1/access-groups/{id}/members/{userId}
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Делает учётную запись userId участником группы; доступ группы к репозиториям она получает со следующего запроса. Добавление существующего участника ничего не меняет; всего допускается не более 10 000 членств (507 membership_limit).
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
userId | путь | string (uuid) | да | — |
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X PUT "$ARKVORY_URL/api/v1/access-groups/$ID/members/$USERID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Исключить учётную запись из группы
DELETE /api/v1/access-groups/{id}/members/{userId}
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Исключает учётную запись userId из группы; доступ, который она имела через группу, прекращается со следующего запроса. Исключение учётной записи, которая не состоит в группе, тоже успешно.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
userId | путь | string (uuid) | да | — |
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/access-groups/$ID/members/$USERID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Предоставить группе доступ к репозиторию
PUT /api/v1/access-groups/{id}/grants/{repository}
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Даёт участникам группы доступ access — read или write — к repository, заменяя прежнее назначение этой группы для него; действует со следующего запроса. Отдельно создавать репозиторий не нужно: назначение делает его видимым для участников. Всего допускается не более 10 000 назначений доступа (507 grant_limit).
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
repository | путь | string | да | — |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
access | string | да | одно из read, write |
Ответы: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X PUT "$ARKVORY_URL/api/v1/access-groups/$ID/grants/$REPOSITORY" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"access":"read"}'Убрать доступ группы к репозиторию
DELETE /api/v1/access-groups/{id}/grants/{repository}
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Удаляет назначение доступа группы к repository; участники сохраняют только тот доступ, который у них есть через другие группы. Удаление несуществующего назначения тоже успешно.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
repository | путь | string | да | — |
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/access-groups/$ID/grants/$REPOSITORY" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Прочитать аудит безопасности
GET HEAD /api/v1/security/audit
Доступ: Администратор · Повтор: Можно повторять (чтение)
Возвращает журнал только для добавления: входы, регистрации, изменения учётных записей, групп, назначений доступа, паролей и персональных токенов, от новых событий к старым, каждое с инициатором, видом учётных данных, целью, результатом и адресом клиента; попытки, отклонённые из-за ограничения частоты, в журнал не попадают. Страницы содержат limit записей (1–100, по умолчанию 50); продолжайте с after, равным next.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
after | запрос | string | нет | целое число десятичными цифрами, передаётся строкой |
limit | запрос | integer | нет | 1–100 |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].id | string | да | целое число десятичными цифрами, передаётся строкой |
items[].occurredAt | string (date-time) | да | — |
items[].actor | string | да | может быть null |
items[].credential | string | да | одно из session, personal-token, service-key, file-key; может быть null |
items[].clientIp | string | да | может быть null |
items[].action | string | да | — |
items[].target | string | да | может быть null |
items[].outcome | string | да | одно из success, failure, denied |
items[].code | string | да | может быть null |
items[].details | object | да | — |
next | string | да | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/security/audit" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Получить свои действующие права
GET HEAD /api/v1/auth/permissions
Доступ: Любой действующий ключ или сессия · Повтор: Можно повторять (чтение)
Возвращает profile вызывающего (managed для управляемого ключа сервиса, иначе legacy), ID его ключа, действующие привязки (каждый репозиторий с точным набором разрешённых там действий) и признак, является ли он начальным сервисным администратором (по ключу восстановления, bootstrap). Используйте для настройки клиента; сервер всё равно проверяет каждый запрос, поэтому изменение прав вступает в силу сразу.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string | да | — |
profile | string | да | одно из legacy, managed |
bindings | массив object | да | не больше 10000 элементов |
bindings[].resource | object | да | — |
bindings[].resource.kind | string | да | одно из repository |
bindings[].resource.id | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
bindings[].actions | массив string | да | 1–24 элементов; без повторов; каждый элемент: одно из repository.read, storage.read, storage.manage, diagnostics.read, artifact.read, artifact.list, artifact.delete, artifact.promote, content.read, upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.read, package.publish, asset.read, asset.write, asset.restore, annotation.read, annotation.write, reference.write, audit.read |
serviceAdministration | boolean | да | — |
credentialId | string (uuid) | нет | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/auth/permissions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"