Автентифікація

Усі запити до AstroWay API автентифікуються через header X-Api-Key. Інших методів немає — жодних OAuth, jwt або session cookies на API-рівні.

Формат ключа

sk_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
sk_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

sk_live_ — production, списує кредити з балансу
sk_test_ — sandbox, запити повертають стабовий відгук (або мінімальний реальний розрахунок), не списують кредити, відмічені в dashboard окремо
Після префікса — 32 символи base62, криптографічно випадкові
Ключ показується в чистому вигляді лише один раз при створенні. Далі в dashboard — тільки перші й останні 4 символи.

Заголовок запиту

POST /v1/chart HTTP/1.1
Host: api.astroway.info
X-Api-Key: sk_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
Content-Type: application/json

Створення і керування ключами

Через dashboard:

api.astroway.info/dashboard/keys
Можна мати до 10 активних ключів на акаунт одночасно
Кожен ключ має label (наприклад production-backend, ci-tests, local-dev)

Через API (для self-service інтеграцій):

curl -X POST https://api.astroway.info/v1/keys \
  -H "X-Api-Key: sk_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-tests", "mode": "test"}'

Best practices

1. Ніколи не клади ключ у фронтенд

Ключ — секрет backend-рівня. Якщо він потрапляє в JS, що виконується в браузері користувача — його видно в DevTools і він витече.

Правильно: свій backend тримає ключ, фронтенд б’ється в твій backend, твій backend — в AstroWay API.

Неправильно:

// ❌ НЕ РОБИ ТАК
fetch('https://api.astroway.info/v1/chart', {
  headers: { 'X-Api-Key': 'sk_live_...' }, // видно в браузері
});

2. Environment variables, не hardcode

# .env (в .gitignore)
ASTROWAY_API_KEY=sk_live_...

// у коді
const key = process.env.ASTROWAY_API_KEY;
if (!key) throw new Error('ASTROWAY_API_KEY is not set');

3. Окремі ключі на різні середовища

production-backend — продакшен
staging-backend — staging
ci-tests — CI/CD pipeline
local-dev-maksym — локальна розробка кожного розробника

Якщо один ключ скомпрометовано — revoke саме його, інші продовжують працювати.

4. Ротація

Рекомендована частота — раз на 90 днів. Або негайно, якщо є підозра на витік.

Ротація без downtime:

Створи новий ключ з тим самим label + -v2
Розгорни його в прод (паралельно зі старим)
Переконайся, що usage тече на новий ключ (dashboard)
Revoke старий

5. Моніторинг usage

Dashboard показує запити по ключах окремо. Якщо раптом один ключ почав робити в 10× більше запитів, ніж зазвичай — це сигнал перевірити.

Можна поставити alert: Settings → Notifications → Alert when daily credits > X.

Помилки автентифікації

Код	Значення
`401 Unauthorized`	Header `X-Api-Key` відсутній або ключ невалідний
`403 Forbidden`	Ключ валідний, але не має scope для цієї дії (наприклад, звичайний ключ намагається керувати іншими ключами)
`402 Payment Required`	Кредити закінчились (на Free) або передплата неактивна
`429 Too Many Requests`	Перевищено rate limit (10/60/300 req/min залежно від плану)

Приклад 401:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "01HXY2A7ZM..."
  }
}

Sandbox mode

Ключі з префіксом sk_test_ працюють у sandbox:

Не списують кредити
Повертають стабовий або мінімальний реальний відгук
Не впливають на статистику production
Доступні ендпоінти — ті ж самі

Корисно для CI/CD, e2e тестів і локальної розробки. Створюється через dashboard одним кліком.

Далі

Кредити та ліміти — як працює білінг і rate limiting
Помилки — повний перелік error-кодів