Secret

API Segreti

Gestisci i segreti del progetto — chiavi API, token e altre credenziali che il tuo progetto distribuito legge daprocess.env a runtime. I valori sono in sola scrittura: entrano tramite questi endpoint ed escono attraverso il runtime del progetto distribuito, e non vengono mai restituiti in alcuna risposta API.

Per informazioni su come funzionano i segreti e su come vengono memorizzati, consulta la guida Segreti & Variabili d'ambiente.

Elenco dei segreti

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

Restituisce l'insieme di segreti definiti su un progetto. Vengono restituiti solo il nome della chiave, gli ultimi quattro caratteri del valore e i timestamp.

Risposta:

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

Creazione o aggiornamento di un segreto

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

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

Idempotente per (projectId, key)— inviare di nuovo la stessa chiave sovrascrive il valore memorizzato. Gli aggiornamenti non vengono conteggiati nel limite per progetto; solo l'aggiunta di una nuova chiave lo fa.

Formato della chiave: UPPER_SNAKE_CASE, 1–64 caratteri, deve iniziare con una lettera. Lunghezza del valore: 1–4096 caratteri.

Risposta:

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

Eliminazione di un segreto

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

Rimuove un segreto. Idempotente — eliminare una chiave che non esiste restituisce comunque success: true, conexistedche indica se una riga è stata effettivamente rimossa.

Risposta:

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

Errori

• 400 VALIDATION_ERROR— Il corpo è malformato, la chiave non supera il controllo del formato, oppure il valore è vuoto o supera i 4096 caratteri.
• 404 NOT_FOUND— Il progetto non esiste o la chiave API del chiamante non è associata ad esso. Per scritture/eliminazioni, il chiamante deve avere anche il ruoloadmin sul team proprietario.
• 409 SECRET_LIMIT_EXCEEDED— Il progetto ha già 25 segreti. Eliminane uno o aggiorna una chiave esistente invece di aggiungerne una nuova.
• 429 RATE_LIMITED— Limite di velocità API superato. Consulta Gestione degli errori per i dettagli.