Autenticación¶

SubX API utiliza claves de API para la autenticación. Todas las solicitudes a la API (excepto /api/health) requieren autenticación.

Crear una Clave de API¶

Para usar SubX API, necesitarás crear una clave de API desde la interfaz web.

Pasos para Crear una Clave de API¶

Inicia sesión en la aplicación web de SubX
Navega a la sección de Perfil o Claves de API en la configuración de tu cuenta
Haz clic en "Crear Nueva Clave de API"
Dale a tu clave de API un nombre descriptivo (ej., "Mi App en Producción", "Pruebas")
Opcionalmente establece una fecha de vencimiento para mayor seguridad
Haz clic en "Generar Clave"

Guarda tu Clave de API

La clave de API solo se mostrará una vez cuando la crees. Asegúrate de copiarla a un lugar seguro inmediatamente. Si la pierdes, necesitarás generar una nueva. :::

Usar tu Clave de API¶

Incluye tu clave de API en el encabezado Authorization de cada solicitud protegida a la API:

Authorization: Bearer {TU_CLAVE_API}

Por ejemplo:

Authorization: Bearer 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t

Ejemplo de Solicitud¶

cURLPythonJavaScript

curl -X GET "https://subx-api.duckdns.org/api/subtitles/search?title=Dexter&limit=10" \
  -H "Authorization: Bearer {TU_CLAVE_API}"

import requests

headers = {
    "Authorization": "Bearer {TU_CLAVE_API}"
}

response = requests.get(
    "https://subx-api.duckdns.org/api/subtitles/search",
    headers=headers,
    params={"title": "Dexter", "limit": 10}
)

print(response.json())

const response = await fetch(
  'https://subx-api.duckdns.org/api/subtitles/search?title=Dexter&limit=10',
  {
    headers: {
      'Authorization': 'Bearer {TU_CLAVE_API}'
    }
  }
);

const data = await response.json();
console.log(data);

Mejores Prácticas de Seguridad¶

1. Mantén tus Claves Seguras¶

❌ Nunca confirmes claves de API en control de versiones (Git)
❌ Nunca compartas claves de API públicamente
✅ Sí usa variables de entorno
✅ Sí usa servicios de gestión de secretos

2. Usa Variables de Entorno¶

# .env (no confirmar en Git)
SUBX_API_KEY={TU_CLAVE_API}

import os

API_KEY = os.getenv("SUBX_API_KEY")

3. Establece Fechas de Vencimiento¶

Establece fechas de vencimiento para claves de API usadas en entornos temporales o de prueba.

4. Rota las Claves Regularmente¶

Para aplicaciones de producción, rota tus claves de API periódicamente (ej., cada 90 días).

5. Usa Claves Diferentes por Entorno¶

Crea claves separadas para desarrollo, staging y producción.

Gestión de Claves de API¶

Visualizar tus Claves¶

Puedes ver todas tus claves de API activas en la aplicación web de SubX:

Ve a Perfil → Claves de API
Verás una lista de todas tus claves con:
Nombre
Fecha de creación
Última fecha de uso
Fecha de vencimiento (si aplica)

Claves Ocultas

Por razones de seguridad, las claves de API completas solo se muestran una vez al crearlas. En la lista, verás una versión parcial de cada clave. :::

Revocar una Clave¶

Si una clave está comprometida o ya no es necesaria:

Ve a Perfil → Claves de API
Encuentra la clave que deseas revocar
Haz clic en "Revocar" o en el ícono de eliminar
Confirma la revocación

Acción Irreversible

Revocar una clave de API es permanente. Cualquier solicitud usando esa clave recibirá un error 401 Unauthorized. :::

Solución de Problemas¶

Error 401 Unauthorized¶

Si recibes un error 401 Unauthorized:

{
  "detail": "Invalid or missing API key"
}

Posibles causas: - ❌ Clave de API faltante del encabezado Authorization - ❌ Esquema incorrecto (el esquema Bearer debe estar seguido por la clave de API) - ❌ Clave de API inválida o revocada - ❌ Clave de API vencida

Verificar tu Clave¶

Prueba tu clave de API con el endpoint de búsqueda:

curl -X GET "https://subx-api.duckdns.org/api/subtitles/search?query=test" \
  -H "Authorization: Bearer {TU_CLAVE_API}"

Si tu clave es válida, recibirás una respuesta 200 OK con resultados de búsqueda.

Próximos Pasos¶

Ahora que tienes tu clave de API, ¡estás listo para comenzar a hacer solicitudes! Dirígete a la Guía de Inicio Rápido para tu primera solicitud a la API.