Головна/Початок роботи/Швидкий старт ENУКРРУС API-довідник (ReDoc) ↗

Швидкий старт

Від нуля до збереженого credential — токен, каталог, створення, статус — за чотири виклики.

Найкоротший корисний шлях крізь сервіс: автентифікуйтеся, подивіться, які провайдери існують, збережіть ключ для одного з них і переконайтеся, що платформа справді ним скористається.

Передумови

  • Базовий URL сервісу. Експортуйте його один раз: export CREDS_BASE=http://localhost:8000 (або домен вашого деплойменту).
  • Токен користувацької площини. У справжніх середовищах це короткоживучий exchange-токен від identity provider з audience: provider-credentials-service — повний флоу описано в User Plane Tokens. Експортуйте його: export TOKEN=....

Локальний шорткат: dev-режим авторизації

Локально запущений сервіс із DEV_AUTH_ENABLED=true приймає identity-заголовки замість JWT: X-Dev-User-Id: <any canonical UUID> та X-Dev-Roles: user (плюс X-Dev-Org-Id/X-Dev-Org-Roles для контексту організації). Замініть заголовок Authorization на ці два в будь-якому прикладі нижче. У production-збірках dev-авторизація відхиляється.

1. Подивіться, які провайдери існують

Викличте GET /v1/providers:

curl -s "$CREDS_BASE/v1/providers?category=mt" \
  -H "Authorization: Bearer $TOKEN"

Кожен елемент несе code — саме проти цього ідентифікатора ви зберігаєте credentials. Оберіть один, наприклад deepl_api, і заберіть його повну картку через GET /v1/providers/{provider_code} — credential_schema у відповіді каже точно, які секретні поля має надіслати наступний крок. Деталі в Provider Schemas.

2. Збережіть credential

Викличте POST /v1/credentials. Власника сервер бере з вашого токена — тіло запиту його ніколи не називає:

curl -s -X POST "$CREDS_BASE/v1/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_code": "deepl_api",
    "name": "My DeepL key",
    "credentials": {"api_key": "your-secret-key"},
    "make_default": true
  }'

import httpx

CREDS_BASE = "http://localhost:8000"
headers = {"Authorization": f"Bearer {TOKEN}"}

r = httpx.post(f"{CREDS_BASE}/v1/credentials", headers=headers, json={
    "provider_code": "deepl_api",
    "name": "My DeepL key",
    "credentials": {"api_key": "your-secret-key"},
    "make_default": True,
})
assert r.status_code == 201, r.text
credential = r.json()

Очікуване 201: запис повертається з masked_credentials (напр. you***key) замість секрету — жоден ендпоїнт користувацької площини ніколи не повертає plaintext (Personal Credentials). make_default: true зробив його вашим default для deepl_api, тож resolve його підхопить.

3. Переконайтеся, чим скористається платформа

Викличте GET /v1/providers/{provider_code}/credential-status:

curl -s "$CREDS_BASE/v1/providers/deepl_api/credential-status" \
  -H "Authorization: Bearer $TOKEN"

Очікувано: "user_credentials_configured": true і "effective_credential_source": "user" — запити на переклад від вашого імені працюватимуть на щойно збереженому ключі. Повне значення кожного поля (включно з різницею між null і false на рівні організації) — в Credential Status.

Куди далі