Origin Grants API
Origin находится в стадии Early Beta и может измениться.
Грант связывает один principal с одним репозиторием или пространство имён и одним правом доступа. Grants API возвращает список гранты, заданных непосредственно на ресурсе, выполняет upsert грант, которым владеет principal, и удаляет его — благодаря этому изменения access можно описывать скриптами и проходить ревью как для кода. Операции write используют те же проверки access, что и Codebase прав доступа UI, и записывают те же аудит-события repository.access_changed и namespace.access_changed.
Эти шесть конечных точек находятся в группе Grants справочника API Origin: List Repository Grants, Upsert Repository Grant, Delete Repository Grant, List Namespace Grants, Upsert Namespace Grant и Delete Namespace Grant. У них общие с Origin API base URL, аутентификация, пагинация и модель ошибок. Эта страница описывает лежащие в их основе концепции.
Principals
Каждый грант указывает ровно один principal.
| Principal | Поле | Что определяет |
|---|---|---|
user | user.id | Пользователя Cursor — по идентификатору user_… в encoded-формате, который использует API организации. |
group | group.id | Группу в Cursor — по её публичному идентификатору grp_…: либо группу, которой владеет команда владельца, либо группу в организации этой команды; он возвращается как publicId в group-маршрутах API организации. Идентификатор g_… в поле id, который принимают эти маршруты, — это другой идентификатор. |
teamGroup | teamGroup.kind | Одну из встроенных групп владеющей команды: members (все участники команды) или admins (администраторы команды). |
Грант для team group задаёт минимальный уровень доступа к ресурсу для каждого участника этой встроенной группы. Для пространства имён это пространства имён floor команды, а для репозитория — override команды для репозитория; при его удалении репозиторий возвращается к пространства имён floor.
Пользователи должны принадлежать организации владельца. Группа должна быть либо группой, которой владеет команда владельца, либо активной группой в организации этой команды; собственные группы команды можно использовать в грантах, даже если команда не связана с организацией. Конечные точки записи отвечают на запрос о несуществующем пользователе или группе точно так же, как и о тех, кто находится за пределами организации, поэтому ответ никогда не подтверждает существование principal. В ответах List не показываются principal, которые больше не соответствуют активному пользователю, группе или владеющей команде.
Разрешения
Для грантов на repository и грантов на пространство имён используются разные уровни прав доступа. И те, и другие соответствуют предустановкам, доступным в Codebase permissions UI.
| Resource | Значения permission |
|---|---|
| Repository | read, write, admin |
| Namespace | PERMISSION_READ, PERMISSION_CONTRIBUTOR, PERMISSION_WRITE, PERMISSION_ADMIN |
PERMISSION_READ, PERMISSION_CONTRIBUTOR и PERMISSION_WRITE дают соответствующий уровень доступа к внутренним repositories пространства имён. PERMISSION_ADMIN управляет самим пространством имён.
В ответах List для гранта с пользовательской политикой возвращается custom (repository) или PERMISSION_CUSTOM (пространство имён). Конечные точки upsert отклоняют такие значения с ошибкой InvalidArgument (HTTP 400) — пользовательские политики не относятся к грантов API.
Scopes
Grants API охватывают четыре scope, все они перечислены в разделе Scopes: repository:settings:read и repository:settings:write для грантов репозитория, namespace:settings:read и namespace:settings:write для грантов пространства имён.
Установки приложения могут иметь все четыре scope, поэтому робот обращается к grants API с токеном доступа установки. Токены доступа пользователя тоже подходят. Запрос scope :write автоматически даёт и соответствующий scope :read. Конечные точки со списками стоят 1 point, а операции записи — 5 points из бюджета, описанного в разделе Rate limits.
Upsert и удаление
Upsert — это запрос POST, который создаёт или заменяет грант, выданный principal на ресурс. У каждого principal есть только один грант на ресурс, поэтому повторный запрос оставляет тот же грант без изменений, а другое право доступа (permission) заменяет предыдущее. При удалении principal указывается в теле запроса, а в ответ возвращается 204 No Content.
В пространстве имён всегда остаётся хотя бы один администратор. Upsert или удаление, из-за которого owner остался бы без администратора, возвращает FailedPrecondition (HTTP 400).