Глоссарий

Дюжина терминов, которые эта вики употребляет точно.

Вендор — компания за API провайдеров (deepl, amazon). Владеет провайдерами в каталоге. Vendors and Providers

Провайдер — один конкретный API-продукт вендора (deepl_api, amazon_translate); единица, под которую хранятся credentials.

Каталог — версионированный YAML, описывающий вендоров, провайдеров, схемы, возможности (capabilities) и политики; read-only по API, одинаков для всех. Его строка версии едет как catalog_version.

Credential — одна сохранённая запись: зашифрованный секретный объект плюс открытая конфигурация, которой владеет пользователь, организация или платформа.

Credential schema / configuration schema — JSON Schema провайдера для секретной и несекретной частей credential. Provider Schemas

Уровень владения (owner type) — кому принадлежит credential: user, organization или platform. Каталог решает по каждому провайдеру, какие уровни могут существовать. Core Concepts

Default — тот единственный credential на пару (провайдер, владелец), который выбирает resolve; не более одного активного default на scope. Defaults and Lifecycle

Resolve — операция сервисной плоскости, отвечающая «на каком credential должен работать перевод этого пользователя», проходя USER → ORGANIZATION → PLATFORM. Возвращает plaintext.

Reveal — операция операторской плоскости, показывающая plaintext одного credential названному человеку; отдельно скоуплена, с обязательной атрибуцией, с audit-записью до ответа. Reveal

Маска (masked_credentials) — редактированная форма, которую возвращает каждое чтение: узнаваемая, непригодная к использованию. Personal Credentials

Плоскость — одна из двух поверхностей API: пользовательская плоскость (/v1/*, exchange-JWT) и сервисная плоскость (/internal/v1/*, client-credentials токены со scope). User Plane Tokens · Service Plane Tokens

Scope — единица разрешений сервисной плоскости: provider-credentials.invoke / .admin / .reveal; ни один не подразумевает другой.

Exchange-токен — короткоживущий пользовательский JWT, отчеканенный ровно под этот сервис (audience: provider-credentials-service).

Менеджер организации — вызывающий, чья сырая орг-роль входит в JWT_ORG_MANAGER_ROLES (по умолчанию owner/admin); единственная identity, которой можно читать и писать credentials организации.

Мягкое удаление / окно восстановления — удаление мгновенно прячет запись; шифротекст живёт ещё несколько дней (по умолчанию 5) до физической очистки. Defaults and Lifecycle

Оптимистичная блокировка (version) — каждая мутация называет версию, которую прочитала; устаревшие записи проигрывают с 409. Errors and Conventions

Audit-событие — неизменяемая запись, которую оставляет каждое значимое действие; секреты никогда не включаются. Audit Events

Correlation id — id запроса, протягивающий нить: вызов клиента → логи сервиса → audit-лента; ваш, если вы его отправите.