Autenticacion

Metodos de autenticacion

Didia soporta dos metodos de autenticacion para la API:

• JWT de usuario — token obtenido mediante el flujo de login. Tiene los permisos del usuario autenticado y esta sujeto a Row Level Security (RLS).
• Service Role Key — clave de servicio con permisos completos que omite RLS. Solo para uso en backend seguro.

Autenticacion con JWT de usuario

Para obtener un token JWT, sigue estos pasos:

• Envia una peticion POST a /auth/v1/token?grant_type=password con el email y password del usuario en el body JSON.
• La respuesta incluye un campo access_token que es el JWT.
• Incluye el token en el header de tus peticiones: Authorization: Bearer access_token.

Ejemplo de peticion:

POST /auth/v1/token?grant_type=password

Content-Type: application/json

{ "email": "usuario@ejemplo.com", "password": "tu-password" }

Duracion y renovacion del token

El token JWT tiene una duracion de 1 hora (3600 segundos). Cuando expira, las peticiones devuelven error 401 Unauthorized.

Para renovar sin requerir credenciales, usa el refresh_token incluido en la respuesta de autenticacion:

POST /auth/v1/token?grant_type=refresh_token

{ "refresh_token": "tu-refresh-token" }

Esto te devuelve un nuevo access_token y refresh_token. Implementa este flujo en tu aplicacion para mantener sesiones activas sin interrupciones.

Autenticacion con OTP (sin password)

Para el flujo de login sin password (magic link / OTP):

• Envia una peticion POST a /auth/v1/otp con el email del usuario.
• El usuario recibira un codigo de 6 digitos por email.
• Verifica el codigo enviando POST a /auth/v1/verify con el email, el token (codigo) y el tipo email.
• La respuesta de verificacion incluye el access_token JWT.

Service Role Key

La clave de servicio permite acceso completo a la API sin las restricciones de Row Level Security. Usala unicamente en servidores backend donde la clave no quede expuesta al cliente.

Encuentra tu Service Role Key en la configuracion de tu proyecto Supabase, seccion API Settings. Enviala en el header:

apikey: tu-service-role-key

Advertencia: la Service Role Key tiene acceso completo a todos los datos de tu academia. Si se expone, cualquier persona podria leer o modificar todos los datos. Nunca la uses en codigo frontend.

Seguridad

• Nunca expongas la Service Role Key en codigo frontend, aplicaciones moviles o repositorios publicos.
• Almacena los tokens y claves en variables de entorno, no en el codigo fuente.
• Usa HTTPS para todas las peticiones (HTTP es rechazado automaticamente).
• Implementa refresh token rotation para mantener sesiones seguras.
• Revoca tokens inmediatamente si sospechas que fueron comprometidos (cierra la sesion del usuario en Supabase).

Row Level Security (RLS)

Las peticiones autenticadas con JWT de usuario estan sujetas a las politicas de Row Level Security (RLS) de PostgreSQL. Esto asegura que cada usuario solo acceda a los datos de su tenant (academia) y a los recursos que tiene permitidos segun su rol (estudiante, instructor, admin).

Preguntas frecuentes

• ¿Cuanto dura el token JWT?

  El access token dura 1 hora (3600 segundos). Despues de ese tiempo, debes usar el refresh token para obtener uno nuevo. El refresh token tiene una duracion mas larga y se renueva con cada uso.

• ¿Puedo usar la Service Role Key desde una aplicacion frontend?

  Absolutamente no. La Service Role Key omite todas las restricciones de seguridad (RLS). Si se expone en el frontend, cualquier persona podria acceder a todos los datos de tu academia. Usala exclusivamente en servidores backend.

• ¿Que pasa si mi token expira durante una operacion?

  La peticion en curso devolvera error 401 Unauthorized. Tu aplicacion deberia detectar este error, renovar el token usando el refresh token, y reintentar la peticion automaticamente.

• ¿Puedo revocar un token JWT?

  Los tokens JWT no se revocan directamente (son stateless). Sin embargo, puedes cerrar la sesion del usuario en Supabase, lo que invalida el refresh token e impide obtener nuevos access tokens.

• ¿La autenticacion OTP funciona para la API?

  Si. El flujo OTP genera el mismo tipo de token JWT que el login con password. Una vez obtenido el token via OTP, usalo exactamente igual en el header Authorization.