Referencia de la API

Secretos

Lista, crea, actualiza y elimina secretos de proyecto a través de la API. Los valores son de solo escritura — nunca se devuelven en texto plano.

Última actualización:

API de secretos

Gestiona los secretos del proyecto: claves de API, tokens y otras credenciales que tu proyecto implementado lee desde process.env en tiempo de ejecución. Los valores son de solo escritura: entran a través de estos endpoints y salen a través del runtime del proyecto implementado, y nunca se devuelven en ninguna respuesta de la API.

Para conocer el funcionamiento de los secretos y cómo se almacenan, consulta la guía de Secretos & Variables de entorno.

Listar secretos

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

Devuelve el conjunto de secretos definidos en un proyecto. Solo se devuelven el nombre de la clave, los últimos cuatro caracteres del valor y las marcas de tiempo.

Respuesta:

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

Crear o actualizar un secreto

POST /api/v1/projects/{projectId}/secrets
{ "key": "STRIPE_SECRET_KEY", "value": "sk_live_..." }

Idempotente por (projectId, key) — volver a publicar la misma clave sobreescribe el valor almacenado. Las actualizaciones no cuentan para el límite por proyecto; solo lo hace agregar una nueva clave.

Formato de clave: UPPER_SNAKE_CASE, 1–64 caracteres, debe comenzar con una letra. Longitud del valor: 1–4096 caracteres.

Respuesta:

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

Eliminar un secreto

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

Elimina un secreto. Idempotente: eliminar una clave que no existe sigue devolviendo success: true, con existedindicando si se eliminó realmente alguna fila.

Respuesta:

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

Errores

  • 400 VALIDATION_ERROR — La forma del cuerpo es incorrecta, la clave no supera la verificación de formato, o el valor está vacío o tiene más de 4096 caracteres.
  • 404 NOT_FOUND — El proyecto no existe o la clave de API del solicitante no tiene alcance sobre él. Para escrituras/eliminaciones, el solicitante también debe tener el rol admin en el equipo propietario.
  • 409 SECRET_LIMIT_EXCEEDED — El proyecto ya tiene 25 secretos. Elimina uno o actualiza una clave existente en lugar de agregar una nueva.
  • 429 RATE_LIMITED — Límite de tasa de la API superado. Consulta Manejo de errores para más detalles.
AnteriorDominios PersonalizadosSiguienteAsesor de IA (streaming)