Sekrety

API sekretów

Zarządzaj sekretami projektu — kluczami API, tokenami i innymi poświadczeniami, które wdrożony projekt odczytuje z process.envw czasie wykonania. Wartości są tylko do zapisu: trafiają do systemu przez te punkty końcowe i wychodzą przez środowisko uruchomieniowe wdrożonego projektu, i nigdy nie są zwracane w żadnej odpowiedzi API.

Aby zapoznać się z tym, jak działają sekrety i jak są przechowywane, przeczytaj przewodnik po sekretach & zmiennych środowiskowych.

Listowanie sekretów

GET /api/v1/projects/{projectId}/secrets

Zwraca zestaw sekretów zdefiniowanych w projekcie. Zwracane są tylko nazwa klucza, cztery ostatnie znaki wartości oraz znaczniki czasu.

Odpowiedź:

{
  "data": {
    "secrets": [
      {
        "key": "STRIPE_SECRET_KEY",
        "lastFour": "aB3x",
        "createdAt": "2026-04-18T09:12:44.000Z",
        "updatedAt": "2026-04-21T15:03:10.000Z"
      }
    ]
  }
}

Tworzenie lub aktualizacja sekretu

POST /api/v1/projects/{projectId}/secrets

{ "key": "STRIPE_SECRET_KEY", "value": "sk_live_..." }

Idempotentne ze względu na (projectId, key)— ponowne przesłanie tego samego klucza nadpisuje przechowywaną wartość. Aktualizacje nie wliczają się do limitu projektu; liczy się tylko dodanie nowego klucza.

Format klucza: UPPER_SNAKE_CASE, 1–64 znaki, musi zaczynać się od litery. Długość wartości: 1–4096 znaków.

Odpowiedź:

{
  "data": {
    "secret": {
      "key": "STRIPE_SECRET_KEY",
      "lastFour": "aB3x",
      "createdAt": "2026-04-18T09:12:44.000Z",
      "updatedAt": "2026-04-21T15:03:10.000Z"
    }
  }
}

Usuwanie sekretu

DELETE /api/v1/projects/{projectId}/secrets/{key}

Usuwa sekret. Idempotentne — usunięcie nieistniejącego klucza nadal zwraca success: true, przy czym existedwskazuje, czy wiersz został faktycznie usunięty.

Odpowiedź:

{ "data": { "success": true, "existed": true } }

Błędy

• 400 VALIDATION_ERROR — Kształt treści jest nieprawidłowy, klucz nie spełnia wymagań formatu lub wartość jest pusta bądź dłuższa niż 4096 znaków.
• 404 NOT_FOUND — Projekt nie istnieje lub klucz API wywołującego nie jest do niego przypisany. W przypadku operacji zapisu/usunięcia wywołujący musi mieć rolę admin w zespole będącym właścicielem projektu.
• 409 SECRET_LIMIT_EXCEEDED — Projekt ma już 25 sekretów. Usuń jeden lub zaktualizuj istniejący klucz zamiast dodawać nowy.
• 429 RATE_LIMITED — Przekroczono limit szybkości API. Sprawdź szczegóły w obsłudze błędów.