Главная/Начало работы/Быстрый старт ENУКРРУС API-справочник (ReDoc) ↗

Быстрый старт

От нуля до сохранённого credential — токен, каталог, создание, статус — за четыре вызова.

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

Предварительные условия

  • Базовый URL сервиса. Экспортируйте его один раз: export CREDS_BASE=http://localhost:8000 (или домен вашего развёртывания).
  • Токен пользовательской плоскости. В реальных окружениях это короткоживущий exchange-токен от identity-провайдера с audience: provider-credentials-service — полный флоу описан в User Plane Tokens. Экспортируйте его: export TOKEN=....

Локальный шорткат: dev-режим аутентификации

Локально запущенный сервис с DEV_AUTH_ENABLED=true принимает identity-заголовки вместо JWT: X-Dev-User-Id: <любой канонический 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.

Куда дальше