Перейти к содержимому

Учётные записи и вход ​

Вход, сессии, персональные токены, пользователи, группы и журнал безопасности.

Операции этой группы с правилом доступа, правилом повтора, параметрами и ответами. Каждый запрос несёт ключ: 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)

ПолеТипОбязателенПравила
namestringда—
passwordstring (password)да—

Ответ 200

ПолеТипОбязателенПравила
tokenstringда—
expiresAtstring (date-time)да—
accountobjectда—
account.idstring (uuid)да—
account.namestringда—
account.administratorbooleanда—
account.enabledbooleanда—

Ответы: 200, 400, 401, 403, 405, 413, 415, 429, 503

Пример

bash
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)

ПолеТипОбязателенПравила
namestringда—
passwordstring (password)да—

Ответ 201

ПолеТипОбязателенПравила
tokenstringда—
expiresAtstring (date-time)да—
accountobjectда—
account.idstring (uuid)да—
account.namestringда—
account.administratorbooleanда—
account.enabledbooleanда—

Ответы: 201, 400, 403, 405, 413, 415, 429, 503

Пример

bash
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

ПолеТипОбязателенПравила
selfRegistrationbooleanда—

Ответы: 200, 400, 403, 503

Пример

bash
curl -X GET "$ARKVORY_URL/api/v1/auth/options"

Перечислить ваши персональные токены доступа ​

GET HEAD /api/v1/auth/tokens

Доступ: Сессия учётной записи (не ключ) · Повтор: Можно повторять (чтение)

Перечисляет персональные токены доступа текущей учётной записи, сначала действующие, с именем, префиксом, областью доступа, временем создания, сроком действия, последним использованием и признаком отзыва; секреты больше не показываются.

Ответ 200

ПолеТипОбязателенПравила
itemsмассив objectдане больше 100 элементов
items[].idstring (uuid)да—
items[].namestringда—
items[].prefixstringда—
items[].scopestringдаодно из read, read-write
items[].createdAtstring (date-time)да—
items[].expiresAtstring (date-time)нетможет быть null
items[].lastUsedAtstring (date-time)нетможет быть null
items[].revokedbooleanда—

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash
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)

ПолеТипОбязателенПравила
namestringда—
expiresAtstring (date-time)нет—
scopestringнетодно из read, read-write

Ответ 201

ПолеТипОбязателенПравила
idstring (uuid)да—
namestringда—
prefixstringда—
scopestringдаодно из read, read-write
createdAtstring (date-time)да—
expiresAtstring (date-time)нетможет быть null
lastUsedAtstring (date-time)нетможет быть null
revokedbooleanда—
tokenstringда—

Ответы: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Пример

bash
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

Пример

bash
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

Пример

bash
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)

ПолеТипОбязателенПравила
currentPasswordstring (password)да—
newPasswordstring (password)да—

Ответы: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 429, 503, 507

Пример

bash
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

ПолеТипОбязателенПравила
idstringда—
administratorbooleanда—
credentialstringнетодно из session, personal-token, service-key, file-key
tokenScopestringнетодно из read, read-write
grantsмассив objectда—
grants[].repositorystringда—
grants[].permissionsмассив stringдакаждый элемент: одно из read, write

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash
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[].idstring (uuid)да—
items[].namestringда—
items[].administratorbooleanда—
items[].enabledbooleanда—

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash
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)

ПолеТипОбязателенПравила
namestringда—
passwordstring (password)да—
administratorbooleanнет—

Ответ 201

ПолеТипОбязателенПравила
idstring (uuid)да—
namestringда—
administratorbooleanда—
enabledbooleanда—

Ответы: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Пример

bash
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)

ПолеТипОбязателенПравила
enabledbooleanнет—
passwordstring (password)нет—

Ответ 200

ПолеТипОбязателенПравила
idstring (uuid)да—
namestringда—
administratorbooleanда—
enabledbooleanда—

Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Пример

bash
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[].idstring (uuid)да—
items[].namestringда—
items[].prefixstringда—
items[].scopestringдаодно из read, read-write
items[].createdAtstring (date-time)да—
items[].expiresAtstring (date-time)нетможет быть null
items[].lastUsedAtstring (date-time)нетможет быть null
items[].revokedbooleanда—

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash
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

Пример

bash
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[].idstring (uuid)да—
items[].namestringда—
items[].membersмассив string (uuid)да—
items[].grantsмассив objectда—
items[].grants[].repositorystringда—
items[].grants[].accessstringдаодно из read, write

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash
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)

ПолеТипОбязателенПравила
namestringда—

Ответ 201

ПолеТипОбязателенПравила
idstring (uuid)да—
namestringда—
membersмассив string (uuid)да—
grantsмассив objectда—
grants[].repositorystringда—
grants[].accessstringдаодно из read, write

Ответы: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Пример

bash
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

Пример

bash
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

Пример

bash
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)

ПолеТипОбязателенПравила
accessstringдаодно из read, write

Ответы: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Пример

bash
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

Пример

bash
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[].idstringдацелое число десятичными цифрами, передаётся строкой
items[].occurredAtstring (date-time)да—
items[].actorstringдаможет быть null
items[].credentialstringдаодно из session, personal-token, service-key, file-key; может быть null
items[].clientIpstringдаможет быть null
items[].actionstringда—
items[].targetstringдаможет быть null
items[].outcomestringдаодно из success, failure, denied
items[].codestringдаможет быть null
items[].detailsobjectда—
nextstringдаможет быть null

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash
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

ПолеТипОбязателенПравила
idstringда—
profilestringдаодно из legacy, managed
bindingsмассив objectдане больше 10000 элементов
bindings[].resourceobjectда—
bindings[].resource.kindstringдаодно из repository
bindings[].resource.idstringдапо шаблону ^[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
serviceAdministrationbooleanда—
credentialIdstring (uuid)нетможет быть null

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash
curl -X GET "$ARKVORY_URL/api/v1/auth/permissions" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Arkvory · ProAnimaStudio