Токени сервісної площини

Client-credentials токени від крос-сервісного auth-сервера — і три scope, що ділять /internal.

Усе під /internal/v1/* автентифікується токеном OAuth 2.0 client-credentials від крос-сервісного auth-сервера (cross-auth): ваш сервіс автентифікується своїм приватним ключем (private_key_jwt), називає цей сервіс ресурсом і отримує короткоживучий RS256 JWT, чий scope вирішує, що йому тут можна. Користувацькі токени на цій площині не працюють ніколи.

Отримання токена

import httpx

token = httpx.post(CROSS_AUTH_TOKEN_URL, data={
    "grant_type": "client_credentials",
    "client_id": "translation-service",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": signed_client_jwt,          # signed with your registered key
    "resource": "https://provider-credentials.internal",
}).json()["access_token"]

resource — це логічний ідентифікатор цього сервісу в auth-реєстрі (не мережевий URL); самі запити далі йдуть на публічний домен сервісу як зазвичай. Які клієнти можуть тримати які scope — це матриця доступу auth-реєстру: онбординг нового споживача — зміна в реєстрі там, а не зміна тут.

Три scope

Scope	Відкриває	Типовий власник
`provider-credentials.invoke`	resolve	runtime-и перекладу
`provider-credentials.admin`	адміністрування credentials	бекенд адмін-панелі
`provider-credentials.reveal`	reveal plaintext	бекенд адмін-панелі, видається окремо

Жоден не включає інший — розділення двонапрямне навмисно: адмін-токен не може читати plaintext (ані через resolve, ані через reveal), а invoke-токен не може адмініструвати. Валідний токен із хибним scope — 403; відсутній/невалідний токен — 401.

Конвенції цієї площини

X-Admin-Actor — адмін- і reveal-виклики атрибутують людину-оператора за сервісом (Internal Admin API); на reveal обов'язковий.
correlation_id — resolve бере його в тілі й простягає крізь audit-стрічку.
Fail-closed — деплоймент без конфігурації сервісної авторизації відповідає 401 на всю площину, замість довіряти будь-кому.

Сама реєстрація (ключ клієнта, resource URI, видача scope) живе в репозиторії та документації auth-сервера; з погляду цього сервісу споживач або приходить із правильним scope, або ні.