Autenticación

Envía tu clave en la cabecera Authorization en cada petición. Las claves llevan el prefijo vokse_sk_ para que sean fáciles de detectar en los logs (trátalas como contraseñas: nunca las subas al repositorio).

Authorization: Bearer vokse_sk_3f8a…

Abre Ajustes → Claves de API en la app de vokse y crea una clave. Verás el secreto exactamente una vez en el momento de la creación, así que cópialo de inmediato. Da a cada integración su propia clave para poder revocar una sin romper las demás.

1. Ve a Ajustes → Claves de API.
2. Pulsa «Crear clave» y dale el nombre de la integración.
3. Selecciona los scopes mínimos que la integración necesita.
4. Copia el secreto: solo se muestra una vez.

Cada clave nace vinculada a un único hogar y solo puede actuar sobre él. Las rutas de la API llevan el id del hogar en el path, pero casi nunca hace falta buscarlo: el segmento literal current se resuelve siempre al hogar de tu clave. Si quieres el id real, pídelo una vez:

curl -H "Authorization: Bearer vokse_sk_3f8a…" \     https://api.vokse.ai/households/current

Todos los ejemplos de esta referencia usan current, así que funcionan tal cual con tu clave. ¿Prefieres el id explícito? Cópialo desde Ajustes → Miembros en la app, o envíalo en la cabecera X-Household-Id en lugar del path.

Cada clave lleva un conjunto de scopes. Una petición solo se permite si la clave posee el scope que el endpoint requiere (mostrado como la insignia de scope en cada endpoint). Los scopes se dividen en tres clases:

• read:*, acceso de solo lectura a un recurso (seguro, idempotente).
• write:*, para crear, actualizar y eliminar en un recurso.
• ai:*, para invocar funciones de IA; se descuentan de tu cuota mensual.

A una clave se le puede asignar una fecha de caducidad en el momento de la creación. Pasada esa fecha, las peticiones fallan con API_KEY_EXPIRED. Rota las claves creando una nueva, desplegándola y revocando luego la antigua. No hay tiempo de inactividad forzado. Las claves revocadas dejan de funcionar de inmediato.