Как подключить внешний API в Replit

Чтобы подключить внешний API в Replit, сохраните ключ провайдера в Secrets (Tools → Setup → Secrets), прочитайте его в коде как переменную окружения и подставьте в запрос. Ниже — весь путь: от пары ключ/значение до проверки соединения и настроек деплоя.

Где в Replit находится Secrets и как добавить ключ

Инструмент Secrets живёт в панели инструментов проекта. В документации Replit описан порядок: откройте проект в Project Editor, выберите Tools в верхней части, найдите раздел Setup и выберите Secrets. Панель откроется со списком секретов проекта, ниже идёт раздел Configurations.

Добавление пары ключ/значение состоит из трёх действий. Нажмите New Secret. Введите Key — имя секрета — и Value — сам секрет. Нажмите Add Secret, чтобы сохранить запись. Найти нужную запись помогает поле Filter Secrets by name.

Дальше записью можно управлять. Рядом с секретом есть меню из вертикальных точек: пункт Edit открывает правку Key или Value, пункт Delete удаляет запись. Кнопка Update Secret сохраняет изменения, Cancel их отбрасывает. Иконка глаза показывает значение, иконка глаза с чертой прячет его обратно.

Для массовой правки откройте меню в заголовке раздела Secrets и выберите Edit as JSON или Edit as .env. Документация Replit предупреждает: перед сохранением просмотрите весь список, потому что массовая правка заменяет существующие секреты проекта.

Секреты можно переиспользовать между проектами. Аккаунтные секреты лежат в Account Settings → Account Secrets. Чтобы привязать их к проекту, откройте Secrets проекта, нажмите иконку цепи с подписью Link Account Secrets, отметьте нужные секреты и выберите Link to this App. Привязанные секреты синхронизируются с аккаунтными; разрыв связи делается через Unlink в меню секрета.

Инструмент хранит и шифрует чувствительные данные проекта: ключи API, токены аутентификации, строки подключения к базе. При добавлении секрета значение автоматически шифруется и становится доступно проекту как переменная окружения. Это убирает жёстко прописанные секреты из кода и снижает риск утечки при публикации проекта, передаче кода или показе экрана.

Secrets и Configurations: в чём разница

В инструменте Secrets два раздела, и оба отдают коду значения как переменные окружения. Разница в характере данных. Секреты — это чувствительная информация, которая остаётся приватной: ключи API, токены аутентификации, строки подключения к базе. Configurations — нечувствительные настройки: уровень логирования, флаги функций, публичные адреса сервисов.

Документация Replit даёт прямой запрет: не храните ключи API, пароли и токены аутентификации как configurations. Для чувствительных значений используйте секреты. Причина в видимости: секрет шифруется при хранении по AES-256 и при передаче по TLS, а configuration задуман как открытая настройка.

Configurations полезны, когда настройка отличается между тестированием в Replit и работой опубликованного проекта. Пример из документации: ключ LOG_LEVEL со значением debug. Для значения, специфичного для одной среды, нажмите More рядом с New configuration и выберите New published app configuration или New testing configuration.

Практическое правило простое. Если значение даёт доступ к чужому сервису или данным — это секрет. Если значение лишь меняет поведение вашего кода и его не страшно увидеть — это configuration. Смешение разделов приводит к тому, что ключ оказывается в открытом виде там, где его увидят другие.

Чтение секрета в Node.js и Python

Секрет становится переменной окружения, поэтому в коде вы обращаетесь к имени. Это и позволяет безопасно коммитить и делиться кодом. Ниже — минимальный модуль конфигурации на двух языках.

Node.js, файл config.js:

const apiKey = process.env.API_KEY;
const baseUrl = process.env.API_BASE_URL || "https://api.example.com";

if (!apiKey) {
  throw new Error("API_KEY не задан: добавьте секрет в Tools > Setup > Secrets");
}

module.exports = { apiKey, baseUrl };

Python, файл config.py:

import os

API_KEY = os.getenv("API_KEY")
API_BASE_URL = os.getenv("API_BASE_URL", "https://api.example.com")

if not API_KEY:
    raise ValueError("API_KEY не задан: добавьте секрет в Tools > Setup > Secrets")

Оба примера объявляют импорты и читают значения из окружения. Секрет нигде не печатается и не попадает в логи. Проверка на пустое значение останавливает запуск с понятным сообщением вместо загадочной ошибки аутентификации позже.

Имена переменных чувствительны к регистру. Если в Secrets ключ записан как API_KEY, то process.env.api_key вернёт undefined. Держите одно написание в секретах и в коде.

Вендорский туториал Twilio для своих ключей использует три отдельные пары: TWILIO_ACCOUNT_SID, TWILIO_API_KEY и TWILIO_API_SECRET, каждая добавляется кнопкой New Secret и подтверждается через Add Secret. Тот же принцип работает для любого провайдера: одна пара ключ/значение на каждую часть учётных данных.

Выбор способа аутентификации в запросе

Метод аутентификации задаёт провайдер API: сверяйте его документацию. Ниже — учебные шаблоны. Замените https://api.example.com и путь /v1/items адресом и методом своего провайдера, добавьте нужные секреты и установите requests для Python. Bearer, Basic и ключ в query-параметре показаны как альтернативы: используйте вариант, который принимает ваш сервис.

Bearer-заголовок. Ключ уходит в заголовке Authorization:

const { apiKey, baseUrl } = require("./config");

async function main() {
  const res = await fetch(`${baseUrl}/v1/items`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const data = await res.json();
  return data;
}

main().catch(() => {
  console.error("Запрос не выполнен: проверьте адрес и настройки доступа");
  process.exitCode = 1;
});

Тот же запрос на Python:

import requests
from config import API_KEY, API_BASE_URL

res = requests.get(
    f"{API_BASE_URL}/v1/items",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=15,
)
data = res.json()

Basic auth. Пара логин/пароль кодируется в base64 и идёт в заголовке Authorization. Для этого примера сохраните логин как API_KEY, пароль как API_SECRET; проверьте, что провайдер ожидает именно такую пару. Кодирование выполняется стандартным модулем Python base64:

import base64
import os
import requests
from config import API_KEY, API_BASE_URL

password = os.environ["API_SECRET"]
token = base64.b64encode(f"{API_KEY}:{password}".encode()).decode("ascii")
res = requests.get(
    f"{API_BASE_URL}/v1/items",
    headers={"Authorization": f"Basic {token}"},
    timeout=15,
)

Query-параметр. Некоторые сервисы принимают ключ прямо в адресе:

res = requests.get(
    f"{API_BASE_URL}/v1/items",
    params={"api_key": API_KEY},
    timeout=15,
)

Используйте способ, который документирует провайдер. Query-параметр может сохранить ключ в адресах и логах; заголовки тоже требуют аккуратной настройки логирования. Basic auth передаёт закодированную пару учётных данных, поэтому отправляйте запрос по HTTPS и не выводите заголовок Authorization. Кодирование base64 обратимо и само по себе не шифрует пароль.

Проверка соединения

Перед тем как строить логику приложения, убедитесь, что ключ дошёл до запроса. Самый быстрый способ — посмотреть переменные окружения из Shell. Документация Replit предлагает команду printenv в инструменте Shell Project Editor: она выводит все переменные окружения проекта. Учтите, что вывод команды показывает значения, поэтому не оставляйте его в общем логе.

Второй способ — короткий тестовый скрипт. Он делает один запрос и печатает только статус ответа, без тела с чувствительными данными:

import requests
from config import API_KEY, API_BASE_URL

res = requests.get(
    f"{API_BASE_URL}/v1/items",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=15,
)
print("status:", res.status_code)

Третий способ — curl из Shell для проверки адреса и заголовка. Перед запуском задайте API_BASE_URL в разделе Configurations: укажите базовый HTTPS-адрес своего провайдера без завершающего слеша. API_KEY должен быть добавлен в Secrets; значение по умолчанию из config.py или config.js само по себе не задаёт переменную Shell.

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $API_KEY" \
  "$API_BASE_URL/v1/items"

Флаг -o /dev/null отбрасывает тело ответа, а -w «%{http_code}» печатает только код. Реестр IANA называет код 200 успешным ответом OK, 401 — Unauthorized, 403 — Forbidden, 404 — Not Found. Успех проверяйте на методе, который требует авторизации; публичный метод не проверит ваш ключ. При отказе сверьте пояснение API: причиной могут быть учётные данные, права или запрошенный ресурс.

Вендорский туториал Twilio показывает тот же приём на своём сервисе: тестовый запрос возвращает имя аккаунта, и это подтверждает, что учётные данные из Replit Secrets приняты. Такой запрос служит проверкой связки «секрет → код → внешний сервис» до написания основной логики.

Секреты в Deployments и переменная REPLIT_DEPLOYMENT

Опубликованный проект читает собственный набор секретов. В документации Replit указан путь: откройте Publishing, выберите Adjust settings и найдите раздел Production app secrets. Просмотрите значения, которые нужны опубликованному проекту, особенно если для тестирования и продакшена используются разные учётные данные.

Сверьте Production app secrets со значениями, нужными опубликованному приложению, особенно если учётные данные тестовой и рабочей среды различаются. Если нужного ключа в среде публикации нет или его имя не совпадает с кодом, проверка в config-модуле остановит запуск с сообщением о пустой переменной.

Replit автоматически задаёт несколько переменных окружения, доступных коду как обычные переменные. Среди них REPLIT_DEPLOYMENT: она равна 1, если код выполняется в опубликованном проекте, и не установлена в остальных случаях. Документация перечисляет и другие: REPLIT_DOMAINS со списком доменов проекта, REPLIT_USER с именем текущего редактора, REPLIT_DEV_DOMAIN с адресом разработки на домене replit.dev. В инструменте Secrets эти переменные не перечислены, но код читает их наравне с остальными.

Проверка среды выглядит так:

import os

if os.getenv("REPLIT_DEPLOYMENT") == "1":
    print("работает опубликованное приложение")
else:
    print("работает проект в редакторе")

Такой признак помогает выбрать разные адреса обратного вызова или разные наборы ключей для теста и продакшена, не меняя код вручную.

Типичные ошибки

Ошибка первая: undefined после деплоя. В редакторе ключ читается, а в опубликованном приложении переменная пустая. Проверьте значения в разделе Production app secrets опубликованного приложения. Проверьте, что нужные пары добавлены именно там, и что имена совпадают с кодом по регистру.

Ошибка вторая: файл .env вместо Secrets. Локальный файл с ключами легко попадает в репозиторий и в чужой доступ. Инструмент Secrets хранит значения зашифрованными и отдаёт их как переменные окружения, поэтому отдельный файл с ключами в проекте не нужен. Массовый импорт при этом возможен: меню в заголовке раздела Secrets открывает Edit as .env.

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

Ошибка четвёртая: статический деплой. Секреты доступны для всех типов деплоя, кроме Static Deployments. Если проект публикуется как статический сайт, серверной части, которая прочитает секрет, там нет. Для запросов к внешнему API с приватным ключом используйте тип деплоя с серверным кодом.

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

Отдельно стоит помнить о видимости. Участники организации без роли Owner не видят значения секретов в интерфейсе, но могут получить их, напечатав переменные окружения. При совместной работе это учитывают при выдаче доступа.

Частые вопросы

Где в Replit добавить ключ API?

Откройте проект в Project Editor, выберите Tools в верхней части, найдите раздел Setup и выберите Secrets. Нажмите New Secret, введите Key и Value, затем нажмите Add Secret. Панель откроется со списком секретов проекта, ниже будет раздел Configurations.

Чем Secrets отличаются от Configurations?

Оба раздела отдают коду значения как переменные окружения. Секреты хранят чувствительные данные: ключи API, токены, строки подключения. Configurations предназначены для нечувствительных настроек вроде уровня логирования. Документация Replit запрещает хранить ключи и пароли как configurations.

Почему после деплоя переменная стала undefined?

Опубликованное приложение читает отдельный набор секретов. Откройте Publishing, выберите Adjust settings и найдите Production app secrets, затем добавьте нужные пары. Проверьте, что имена совпадают с кодом по регистру, и что тип деплоя поддерживает секреты.

Можно ли хранить ключ в файле .env?

Файл с ключами легко попадает в репозиторий и в чужой доступ. Инструмент Secrets хранит значения зашифрованными и отдаёт их как переменные окружения. Массовый перенос возможен через Edit as .env в меню раздела Secrets, но перед сохранением просмотрите весь список.

Как проверить, что ключ дошёл до API?

Выполните короткий запрос к защищённому методу и выведите только код ответа. В реестре IANA 200 — OK, 401 — Unauthorized, 403 — Forbidden. Сверьте значение и пояснение ответа с документацией API; сам факт наличия переменной окружения ещё не подтверждает правильность ключа.