Authentication: key and permissions
/docs/authenticationcurrentМашинный перевод с английского· проверено 2026-10-25
Статус: current · проверенный: 2026-10-25, проверено на выдачу токенов, паспорт, scope регистра и охранника; нет live используемые учетные данные владелец: гладиатр API документация · Служить: GET /docs/authentication
1. Получить a key
Открой. shop кабинет → API доступ в admin.vizen.shop/api-access и выдать личный API Токен для задания. Выберите required разрешения, contour и
- Срок действия. key показан один раз; Сервер сохраняет свой хеш.
Выдача и отзыв ключей - это действия кабинета, а не операции, делегированные на PAT.
Выберите самые узкие разрешения и конечный срок действия для временной работы.. Чувствительные разрешения требуют shop owner или администратором. scope ссылка идентифицирует их; не выводите чувствительность от предустановленного name. Существующие ключи не автоматически приобретают новые права..
2.Проверить подлинность и прочитать паспорт
API base: https://api.vizen.shop. Отправь это header По аутентифицированным запросам:
Authorization: Bearer <personal-api-token>Поставка secret через защищенную среду процесса с трассировкой оболочки и HTTP header - Нетрудоспособный. VIZEN_TOKEN уже обеспечено надежно, тот first запрос является:
curl --fail-with-body -sS https://api.vizen.shop/v1/account/token \
-H "Authorization: Bearer $VIZEN_TOKEN"Читайте возвращенный паспорт before Любое письмо:
| Поле | Как его использовать |
|---|---|
company_id, api_base | Определить shop и API для этого key; просьба's company_id cannot Предоставление доступа к другому shop. |
scopes | Разрешения, фактически предоставленные на это key. |
capabilities | Поддерживаемые действия в рамках key's scopes, contour и применимым role Ворота. scope Только не доказывает, что метод можно назвать. |
contour, writes_to_live | prod пишет в live shop; dev Поддерживается catalogue/content/file изменения в a draft. Скажи owner Когда изменения будут видны сразу. |
mode, mode_guide | Следуйте фактическому рабочему процессу: full, draft, draft_publish, или resource-связанный folder_draft. Публикация нуждается в owner's инструкция. |
scopes_denied | Права не предоставлены; не обнаруживайте их в судебном порядке. |
live_operations_denied, prod_sensitive_methods_denied | Методы a DEV key cannot Звонок; draft не является отдельной копией all shop операции. |
warnings | Пропускай. warnings в owner в full before Большая книга. |
store.storefront_url | Открой это. address Чтобы проверить result; включает в себя active custom Домены, но стоя's выполненный с возможностью base переопределяет его — если он указывает на другую витрину магазина, сообщите о несоответствии. api_base. Не угадывай, shop URL. |
store.currency, store.language | Используйте shop's фактический settings; Правила ценообразования относятся к Каталог. |
expires_at | RFC3339 UTC истечения срока, или null для key без истечения срока. |
guides, docs_url | Продолжать документацию, относящуюся к key. |
resource (когда присутствует) | А. folder-связанный key ограничивается названным site folder и DEV draft; смотреть Файлы хранения. |
The contour принадлежит к key. dev_header_allowed это false: ни один из них header ни переключатели параметров запроса PROD/DEV. Запросить подходящий key через owner Когда задача требует иного contour.
3.Проверять разрешения без проверки мутаций
Использовать scopes.json для current scope список, чувствительность и contour ограничения. OpenAPI, или семейной секции, такой как /openapi.json?scope=catalog, Для каждого метода's Требования. партнерская проекция исключают методы, закрытые для PAT. Не надо. keep копировать scope Матрица в вашей интеграции.
для работы с каталогом image загрузка, запрос только необходимого каталога и операции хранения; используйте паспорт и метод ссылки для проверки exact формы и представленные документы leads Иметь отдельные разрешения: forms:* делать не открытый свинец data. Другие семьи также не подразумеваются catalog:*.
4. ошибки и молчание ignored предположения
| Ответ | Значение и следующий action |
|---|---|
401 в паспорте, invalid_token | Missing/wrong key формат, или unknown, отменены или expired key. Проверьте безопасность secret delivery; Спроси owner Замена, когда это необходимо. |
403 PAT_SCOPE_MISSING | Частный метод требует scope отсутствующий в этом key. Читать required_scope в error; просить required Доступ вместо повторного использования. |
403 PAT_METHOD_NOT_ALLOWED | Метод закрыт для личного API Используйте поддерживаемую альтернативу или используйте owner выполнять action в кабинете. scopes Не открывайте его. |
403 PAT_CONTOUR_MISMATCH | The DEV key cannot доступ к live Операция или метод. Следуйте за паспортом's Отрицательные списки и их owner Выберите подходящий рабочий процесс. |
другой 403 | А. role, resource или узлы доступа, специфичные для операции, могут по-прежнему отклонять доступ.'s справочный и устранение неполадок. |
А. public Запрос на каталог может ответить 200 без безвозмездно `catalog:read`, возвращать анонимный view: только public data, без owner-только draft visibility. Поэтому "200" /products” не является аутентификацией test. Успешный Паспорт проверяет key; Успешное письмо требует перечитывания
- объект и проверка витрины магазина. unknown scope гранты extra доступ.
5. Исключение, отзыв и secret обработка
Никогда не ставьте ключи в простой текст source files, HTML, браузер-side JavaScript, бревна, отчеты, ответы в чате или обязательства. Не встраивайте их в URL. Держите учетные данные выгруженный из site Артефакты и резервные копии, предназначенные для совместного использования.
А. key остается пригодным для использования до истечения срока его действия или отмены, при условии соблюдения его основных и resource - Ворота доступа. null Срок годности не делает его безопасным для сохранения: Утечки не иссякают сами. После временного задания, у вас есть owner отменять тот key в кабинете's API доступ page. Отзыв и замена подозреваемого просочившегося key Паспорт отклоняет старый, key с 401; public Запросы на каталоги могут быть успешными анонимно и не являются отзывом. test.
Продолжайте с Быстро стартовать, Руководство по задачам, или Агентский навык входа.