# Secretos y variables de entorno

Dos tipos de valores quedan fuera de su código: **secretos** (contraseñas y <Term id="api-key">claves de API</Term>) y **variables de entorno** (ajustes simples, como una dirección pública). Guardados en el <Term id="project">proyecto</Term>, una clave nunca termina en su repositorio ni en un chat con la IA, y usted cambia un valor sin cambiar código.

<Callout type="info" title="Cómo se protegen los secretos">
Los secretos se cifran con un servicio de claves administrado. Una vez guardado, el valor queda oculto: nadie puede leerlo en la aplicación ni por la API, pero sus aplicaciones sí pueden usarlo.
</Callout>

## Antes de empezar [#antes-de-empezar]

- Agregarlos y cambiarlos requiere el <Term id="roles">rol</Term> **Propietario** o **Administrador** en el proyecto.
- La aplicación le pide confirmar su identidad primero: seleccione **Verifique para ver** y luego **Continuar** en "Confirme que es usted".

## Dónde encontrarlos [#dónde-encontrarlos]

- **Claves** en la barra lateral, bajo **Lanzamiento**, cubre todos los proyectos. Elija uno; la página indica si puede cambiar o solo ver.
- Dentro de un proyecto, abra **Configuración** y vaya a **Claves**.

## ¿Secreto o variable? [#secreto-o-variable]

| Use un | Para | Después de guardar |
| --- | --- | --- |
| Secreto | Contraseñas, tokens y claves de API. | Oculto. Puede reemplazarlo, desactivarlo o eliminarlo, nunca leerlo. |
| Variable | Ajustes simples que sus aplicaciones pueden leer. | Visible para quienes pueden abrir la sección Claves. |

## Agregar un secreto [#agregar-un-secreto]

<ForEveryone>
<Steps>
<Step>
### Abra Secretos [#abra-secretos]
En la sección **Claves** del proyecto, seleccione **Verifique para ver** si se le pide, vaya a **Secretos** y abra **Agregar un secreto**.
</Step>
<Step>
### Póngale nombre [#póngale-nombre]
Escriba un **Nombre**, por ejemplo `GITHUB_TOKEN`.
</Step>
<Step>
### Elija cómo se usa [#elija-cómo-se-usa]
En **Cómo se usa**, elija una opción:
- **Se agrega a las solicitudes a un sitio web**: escriba el **Sitio web** (por ejemplo `api.github.com`). Klarety agrega el secreto a cada solicitud allí, así su código nunca tiene el valor. Opcionalmente, defina el **Encabezado** (por ejemplo `Authorization`) y un **Prefijo** (por ejemplo `Bearer `).
- **Una variable en sus aplicaciones desplegadas**: su aplicación desplegada la lee como una variable de entorno con este nombre.
</Step>
<Step>
### Pegue el valor y elija el alcance [#pegue-el-valor-y-elija-el-alcance]
Pegue el **Valor**. En **Alcance**, elija **Studio**, **Vista previa** o **Producción**.
</Step>
<Step>
### Guarde [#guarde]
Seleccione **Agregar secreto**.
</Step>
</Steps>

<Screenshot src="/docs/_media/dashboard-environment-keys-for-project.png" alt="El formulario Agregar un secreto" />
</ForEveryone>

<ForDevelopers>
Los secretos también son de solo escritura en el SDK: `projects.secrets` devuelve nombres, sitios, versiones y último uso, nunca un valor.

```python title="secrets.py"
from klarety import Nexus

nx = Nexus.connect()
project_id = "YOUR_PROJECT_ID"

nx.projects.set_secret(
    project_id,
    "GITHUB_TOKEN",
    "ghp_your_token",
    host="api.github.com",
    use="host",
    environments=["studio", "production"],
)

nx.projects.set_secret(project_id, "STRIPE_KEY", "sk_live_your_key", use="env")

for secret in nx.projects.secrets(project_id)["secrets"]:
    print(secret["name"], secret["host"], secret["version"])

nx.projects.disable_secret(project_id, "STRIPE_KEY")
nx.projects.delete_secret(project_id, "STRIPE_KEY")
```

`use="host"` agrega el secreto a las solicitudes a `host`, con `inject_header` (por defecto `Authorization`) e `inject_prefix` (por defecto `Bearer `). `use="env"` lo define como una variable con el nombre del secreto. `environments` acepta `studio`, `preview` y `production`. Para traer un archivo dotenv, `nx.projects.import_secrets(project_id, entries, host=...)` agrega un secreto por clave.
</ForDevelopers>

## Cambiar o quitar un secreto [#cambiar-o-quitar-un-secreto]

Cada secreto muestra su alcance, su versión y cuándo se usó por última vez.

- **Reemplazar**: sobrescribe el valor para siempre. El nuevo se usa desde la próxima solicitud.
- **Desactivar**: pausa el secreto sin eliminarlo.
- **Eliminar**: deja de enviarse de inmediato y no se puede recuperar.

## Agregar una variable [#agregar-una-variable]

<ForEveryone>
<Steps>
<Step>
### Abra Entorno [#abra-entorno]
En la sección **Claves** del proyecto, vaya a **Entorno** y seleccione **Agregar variable**.
</Step>
<Step>
### Complétela [#complétela]
Escriba el nombre y el **Valor**, y elija su alcance (Studio, Vista previa o Producción). Márquela como **Compilación** si su aplicación la necesita al compilarse, o **Público** si está pensada para verse, por ejemplo en una página web.
</Step>
<Step>
### Guarde [#guarde-1]
Seleccione **Guardar**. Si quitó o renombró una variable, la aplicación le pide confirmar.
</Step>
</Steps>
</ForEveryone>

<Screenshot src="/docs/_media/dashboard-environment-keys-for-project.png" alt="La sección Entorno de las Claves del proyecto con el formulario Agregar variable" />

<ForDevelopers>
`set_env` reemplaza el conjunto completo, y solo sobre la versión que usted leyó, para que dos personas no se sobrescriban sin darse cuenta. Una `version` desactualizada recibe un conflicto 409.

```python title="environment.py"
from klarety import Nexus

nx = Nexus.connect()
project_id = "YOUR_PROJECT_ID"

current = nx.projects.env(project_id)
entries = {**current["entries"], "APP_TITLE": "Sales dashboard"}

nx.projects.set_env(
    project_id,
    entries,
    version=current["version"],
    scopes={
        **current["scopes"],
        "APP_TITLE": {"environments": ["production", "preview"], "public": True},
    },
)
```
</ForDevelopers>

## Cuándo se aplica un cambio [#cuándo-se-aplica-un-cambio]

- Los <Term id="studio">Studios</Term> y <Term id="deploy">despliegues</Term> nuevos reciben una variable cambiada.
- El código que lee una variable quitada o renombrada deja de encontrarla.
- Un secreto reemplazado se usa desde la próxima solicitud. Uno eliminado se detiene de inmediato.

<Callout type="warn" title="Vuelva a desplegar tras un cambio">
Una aplicación en ejecución conserva sus valores anteriores hasta que se despliegue de nuevo. Consulte [Desplegar una aplicación](/docs/es/deploy/deploy-an-app).
</Callout>

## Si algo sale mal [#si-algo-sale-mal]

<Accordions>
<Accordion title="Los secretos y las variables siguen ocultos">
No ha confirmado su identidad recientemente. Seleccione **Verifique para ver**.
</Accordion>
<Accordion title="No puede agregar un secreto">
Solo el Propietario y los Administradores del proyecto pueden agregar o cambiar secretos. Pídaselo a uno de ellos.
</Accordion>
<Accordion title="Cree que un secreto se filtró">
Genere un valor nuevo en su origen y luego **Reemplácelo** aquí. Si cree que se filtraron las credenciales del proyecto, use **Cortar el acceso del proyecto** en la Zona de peligro. Consulte [Configuración del proyecto](/docs/es/projects/settings).
</Accordion>
</Accordions>

## Siguientes pasos [#siguientes-pasos]

- [Configuración del proyecto](/docs/es/projects/settings)
- [Desplegar una aplicación](/docs/es/deploy/deploy-an-app)
- [Seguridad](/docs/es/get-started/security)