Autenticación

Cada llamada usa un token de corta duración. El SDK cambia su clave de API por un token de una hora y lo renueva por usted. Con HTTP directo, usted hace el cambio con una sola solicitud.

Claves de APICopiar el enlace

Una clave de API actúa como su espacio de trabajo y gasta sus créditos. 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 explica cómo leerlo desde el código.

Cree una claveCopiar el enlace

Abra SDK y APICopiar el enlace

Vaya a ConfiguraciónSDK y API. Si la página le pide verificar que es usted, hágalo.

Complete la claveCopiar el enlace

Seleccione Crear clave y defina Nombre, Acceso y Vence.

Cópiela ahoraCopiar el enlace

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.

Use una clave desde PythonCopiar el enlace

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

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:

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 tokenCopiar el enlace

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 comandosCopiar el enlace

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

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

klarety logout borra la clave del llavero. Vea CLI para todos los comandos.

Use una clave desde HTTP directoCopiar el enlace

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

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

La respuesta:

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

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

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.

Rote una claveCopiar el enlace

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:

Cree la clave nuevaCopiar el enlace

En ConfiguraciónSDK y API, cree una clave con el mismo Acceso que la anterior.

DespliéguelaCopiar el enlace

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.

Revoque la clave anteriorCopiar el enlace

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.

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

Qué puede salir malCopiar el enlace

Próximos pasosCopiar el enlace

• Inicio rápido del SDK para ejecutar una primera consulta.
• Errores para cada código de estado.
• Límites y límites de solicitudes para leer lo que permite su plan.