Открытый API запросов прав доступа

Приложения используют access token, чтобы запрашивать роли, ресурсы, права API и области данных пользователя, а также объявлять собственные сущности данных.

Открытый API расположен под /api/v1/open/ и принимает только Bearer-токены, выданные сервером авторизации; он не использует cookies и не требует CSRF-токенов. Токен сразу перестаёт работать, как только отзывают его самого или его грант.

Эндпоинты

Эндпоинт	Токен	Описание
`GET /api/v1/open/me/authorization`	Пользовательский токен, `permissions`	Роли, ресурсы и права API пользователя в этом приложении; поддерживает `If-None-Match` (304)
`GET /api/v1/open/me/permissions?permission=a&permission=b`	Пользовательский токен, `permissions`	По одному отвечает, есть ли каждое из указанных прав (за раз от 1 до 100)
`GET /api/v1/open/me/data-access`	Пользовательский токен, `permissions`	Правила ролей для сущностей данных этого приложения: области, условия, подразделения, а также подразделения пользователя (включая дочерние), группы и должности; поддерживает ETag
`PUT /api/v1/open/catalog/data-entities`	Собственный токен клиента, `catalog`	Объявляет все сущности данных этого приложения, заменяя предыдущее объявление

Пример

curl -H "Authorization: Bearer $TOKEN" https://grantforge.example.com/api/v1/open/me/authorization

{
  "application": "shop",
  "accountId": "100203911213113344",
  "tenantId": "100203900000000000",
  "username": "sam",
  "version": 8121,
  "roles": ["shop-buyers"],
  "resources": ["shop.orders", "shop.orders.btn.create"],
  "permissions": ["orders.read", "orders.create"],
  "computedAt": "2026-10-05T03:12:45Z"
}

Идентификаторы учётных записей и тенантов возвращаются строками, поскольку они выходят за пределы диапазона целых чисел, который JavaScript представляет точно; version — это номер версии прав.

Кэширование и версионирование

Ответы authorization и data-access содержат ETag. Закэшируйте ответ и в следующий раз пришлите If-None-Match: если права не изменились, сервер почти без затрат возвращает 304. Любое изменение выдач, назначений, каталога ресурсов или политик данных меняет номер версии. SDK кэшируют ответы на 30 секунд по умолчанию, а затем повторно проверяют их по ETag.

Объявление сущностей данных

Приложение объявляет свои сущности данных собственным конфиденциальным клиентом (client credentials и скоуп catalog):

{
  "entities": [
    {
      "code": "order",
      "name": "订单",
      "owned": true,
      "unitBased": false,
      "fields": [
        { "code": "status", "name": "状态", "type": "CHOICE", "choices": ["NEW", "PAID", "SHIPPED"] },
        { "code": "total", "name": "金额", "type": "NUMBER" }
      ]
    }
  ]
}

После объявления сущности появляются в редакторе прав на данные роли как <应用编码>:<实体编码> (например, shop:order). owned означает, что у каждой строки есть учётная запись-владелец (включает область «только собственные записи»), а unitBased — что каждая строка относится к подразделению (включает области по подразделениям). Приложения на Java не обязаны писать этот запрос вручную: стартовый пакет объявляет сущности автоматически по аннотации @GrantForgeEntity.

Ошибки

Все ошибки — это problem details по RFC 9457 с полями code и requestId:

Статус / код ошибки	Значение
401	Токена нет или он больше недействителен; войдите снова
`GF-SECURITY-003`	Ожидается пользовательский токен, а передан собственный токен клиента
`GF-SECURITY-004`	В токене не хватает обязательного scope
`GF-SECURITY-005`	Ожидается собственный токен клиента, а передан пользовательский токен
`GF-AUTHZ-052`	Объявленные сущности данных некорректны; в `errors` перечислены конкретные проблемы