# Autenticación

Cada llamada usa un token de corta duración. El <Term id="sdk">SDK</Term> cambia su <Term id="api-key">clave de API</Term> por un token de una hora y lo renueva por usted. Con HTTP directo, usted hace el cambio con una sola solicitud.

## Claves de API [#claves-de-api]

Una clave de API actúa como su <Term id="workspace">espacio de trabajo</Term> y gasta sus <Term id="credits">créditos</Term>. Cada clave tiene:

- un **Nombre**, para distinguir las claves después;
- un nivel de **Acceso**, que decide qué puede hacer la clave (el más amplio es "Total, incluidos cambios de esquema");
- una fecha opcional en **Vence**;
- **Orígenes del navegador** opcionales, solo para claves que se usan desde una página web. Las claves de navegador solo pueden leer.

Solo los administradores del espacio de trabajo administran claves. Su plan limita las claves activas; la página de claves muestra cuántas tiene, y [Límites](/docs/es/developers/limits) explica cómo leerlo desde el código.

### Cree una clave [#cree-una-clave]

<Steps>
<Step>
### Abra SDK y API [#abra-sdk-y-api]
Vaya a <AppLink to="settings.sdk-api" />. Si la página le pide verificar que es usted, hágalo.
</Step>
<Step>
### Complete la clave [#complete-la-clave]
Seleccione **Crear clave** y defina **Nombre**, **Acceso** y **Vence**.
</Step>
<Step>
### Cópiela ahora [#cópiela-ahora]
Seleccione **Crear clave** en el formulario. **Su nueva clave de API** se muestra una sola vez: cópiela a un lugar seguro, como su gestor de secretos.

<Screenshot src="/docs/_media/create-api-key.png" alt="Su nueva clave de API, mostrada una sola vez al crearla" />
</Step>
</Steps>

## Use una clave desde Python [#use-una-clave-desde-python]

El SDK busca la clave en este orden: el argumento `api_key` y luego la variable de entorno `KLARETY_API_KEY`.

```python title="connect.py"
import os

from klarety import AuthError, Nexus

try:
    nexus = Nexus.connect()  # reads KLARETY_API_KEY
except AuthError as refused:
    raise SystemExit(f"Could not sign in: {refused}")

with nexus:
    print(nexus.account().roles)
```

Pasar la clave de forma explícita funciona igual:

```python
nexus = Nexus.connect(api_key=os.environ["MY_KLARETY_KEY"])
```

`connect()` lanza `AuthError` de inmediato cuando no encuentra una clave (`pass an api key or set KLARETY_API_KEY`) o cuando la clave es rechazada (`api key rejected`). Una clave rechazada es incorrecta, fue revocada o venció.

### Cómo se renueva el token [#cómo-se-renueva-el-token]

`connect()` guarda el token en memoria. Unos cinco minutos antes de que se cumpla la hora, la siguiente llamada vuelve a cambiar la clave, así un proceso largo (un worker, un notebook, un servidor) sigue funcionando.

## Use una clave desde la línea de comandos [#use-una-clave-desde-la-línea-de-comandos]

La CLI guarda su clave en el llavero del sistema operativo, nunca en un archivo:

```bash
klarety login "paste-your-key-here"
klarety sql "SELECT 1 AS ok"
```

`klarety logout` borra la clave del llavero. Vea [CLI](/docs/es/developers/cli) para todos los comandos.

## Use una clave desde HTTP directo [#use-una-clave-desde-http-directo]

Sin el SDK, primero cambie la clave por un token.

<Endpoint method="POST" path="/v1/token" />

```bash
curl -s https://api.klarety.ai/v1/token \
  -H "Content-Type: application/json" \
  -d "{\"api_key\": \"$KLARETY_API_KEY\"}"
```

La respuesta:

```json
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Envíe el token en todas las demás solicitudes:

```bash
curl -s https://api.klarety.ai/v1/account \
  -H "Authorization: Bearer $TOKEN"
```

`expires_in` está en segundos; vuelva a cambiar la clave antes de que se agote. Un token ausente, incorrecto o vencido siempre recibe el mismo cuerpo `401`, así nadie sabe qué verificación falló. Vea [Errores](/docs/es/developers/errors).

## Rote una clave [#rote-una-clave]

Rote una clave de forma periódica, cuando alguien con acceso se va, o si pudo filtrarse. En este orden, la rotación no interrumpe su servicio:

<Steps>
<Step>
<Screenshot src="/docs/_media/sdk-api-page-list-of-all-keys.png" alt="La configuración de SDK y API con todas las claves de API del espacio de trabajo" />

### Cree la clave nueva [#cree-la-clave-nueva]
En <AppLink to="settings.sdk-api" />, cree una clave con el mismo **Acceso** que la anterior.
</Step>
<Step>
### Despliéguela [#despliéguela]
Reemplace la clave anterior donde se usaba (gestor de secretos, entorno del servidor) y reinicie o vuelva a desplegar. Confirme con `nexus.account()` que inicia sesión.
</Step>
<Step>
### Revoque la clave anterior [#revoque-la-clave-anterior]
Seleccione **Revocar** en la clave anterior y luego **Revocar clave**. Todo lo que aún la use deja de funcionar de inmediato, y no se puede deshacer.
</Step>
</Steps>

¿Llegó al límite de claves de su plan? Revoque primero una que no use.

<Callout type="warn" title="Una clave filtrada">
Revóquela primero y luego cree un reemplazo. Unos minutos sin servicio cuestan menos que una clave que funciona para otra persona.
</Callout>

## Qué puede salir mal [#qué-puede-salir-mal]

| Problema | Causa | Solución |
| --- | --- | --- |
| `AuthError` en `connect()` | Clave ausente, mal escrita, revocada o vencida. | Revise la variable, o cree una clave nueva. |
| `RefusedError` en una llamada | El **Acceso** de la clave no permite esta llamada. | Use una clave con el acceso que necesita. |
| No aparece **Crear clave** | Usted no es administrador del espacio de trabajo. | Pida a un administrador que cree la clave. |
| `401` desde HTTP directo después de una hora | El token venció. | Llame de nuevo a `POST /v1/token`. |

## Próximos pasos [#próximos-pasos]

- [Inicio rápido del SDK](/docs/es/developers) para ejecutar una primera consulta.
- [Errores](/docs/es/developers/errors) para cada código de estado.
- [Límites y límites de solicitudes](/docs/es/developers/limits) para leer lo que permite su plan.