Autenticación

🔑 Autenticación

La API de Uspeech utiliza claves API por usuario. Cada clave pertenece a una única cuenta de usuario y hereda exactamente los permisos que ese usuario tiene en la aplicación web: los proyectos y equipos que puede ver, las transcripciones que puede leer, los archivos que puede subir.

Hoy no existe una clave compartida de “servicio” o de “equipo” — elige al usuario en cuyo nombre debe actuar la clave y créala para ese usuario.

1. Crear una clave API

Las claves API se administran desde tu panel de Perfil en la aplicación web.

Inicia sesión en app.uspeech.io con el usuario en cuyo nombre debe actuar la clave.
Abre Perfil desde el menú de usuario.
Localiza la sección Claves API y haz clic en Crear clave API.
La clave en texto plano se muestra una sola vez en este momento. Cópiala de inmediato. La clave recibe un nombre autogenerado que puedes usar para identificarla más adelante en la lista.

⚠️ Importante: la clave en texto plano solo se muestra al crearla. Uspeech solo guarda un hash, por lo que una clave perdida no se puede recuperar — tendrás que crear una nueva y revocar la anterior.

2. Úsala en tus peticiones

Envía la clave en el encabezado Authorization, con el prefijo Api-Key:

Authorization: Api-Key <prefix>.<secret>

Una petición completa se ve así:

curl https://app.uspeech.io/api/transcripts/ \
  -H "Authorization: Api-Key abc123.longersecretstringhere"

Eso es todo — sin paso de login adicional, sin intercambio de tokens.

3. Alcance (scoping)

Una clave hereda la visión que su usuario tiene del sistema:

Listar transcripciones (GET /api/transcripts/) devuelve solo las transcripciones cuyo archivo pertenece a un proyecto que el usuario puede ver.
Subir un archivo (POST /api/files/) requiere project=<id> apuntando a un proyecto del que el usuario es dueño, administrador del equipo o con el que se le ha compartido explícitamente.
Un usuario inactivo (is_active = False) no puede usar la clave — las peticiones se rechazan aunque la clave en sí siga vigente.

Trata la clave con el mismo nivel de criticidad que la contraseña del usuario.

4. Revocar una clave comprometida

Si una clave se filtra, revócala de inmediato:

Abre Perfil y baja hasta la sección Claves API.
Localiza la clave por su Nombre o Prefijo (la parte previa al . en la clave en texto plano).
Haz clic en Revocar.

Las claves revocadas devuelven 403 Forbidden en cada petición. Emite una nueva clave para la integración y actualiza el despliegue que la utiliza.

5. Mejores prácticas de seguridad

🔒 Guarda las claves en un gestor de secretos o variable de entorno, nunca en el control de versiones.
🔁 Rota las claves de forma periódica y de inmediato ante cualquier sospecha de exposición.
🧑‍🤝‍🧑 Usa una cuenta de usuario dedicada por integración para poder revocarla de forma independiente. No reutilices la clave de una cuenta personal para un servicio compartido.

Resolución de problemas

Síntoma	Causa probable
`401 Unauthorized` / `403 Forbidden` sin encabezado	Falta el encabezado `Authorization` o el prefijo no es exactamente `Api-Key` (con el espacio final)
`403 Forbidden` con una clave aparentemente válida	La clave está revocada, el usuario está inactivo, o la parte secreta no coincide
`404 Not Found` con un ID de proyecto conocido	El proyecto existe pero no es visible para el usuario de la clave

Consulta Códigos de estado y errores para la lista completa de códigos de respuesta.