Saltar al contenido principal

Token Refresh

Intercambia un token refresh por un nuevo token de acceso y token refresh. Usa esto para mantener sesiones de usuario sin requerir re-login.

Endpoint​

POST /api/v1/auth/refresh

Autenticación​

No se requiere autenticación, pero requiere token refresh válido.

Request​

Content-Type​

application/json

Request Body​

CampoTipoRequeridoDescripción
refresh_tokenstringSíToken refresh válido del login o refresh anterior

Ejemplo de Request​

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response​

Response Exitoso (200 OK)​

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
Nuevos Tokens para Ambos

Este endpoint devuelve tanto un nuevo token de acceso como un nuevo token refresh. Siempre reemplaza ambos tokens en tu almacenamiento.

Campos del Response​

CampoTipoDescripción
access_tokenstringNuevo token de acceso JWT (expira en 30 minutos)
refresh_tokenstringNuevo token refresh JWT (expira en 7 días)
token_typestringSiempre "bearer"

Rotación de Tokens​

Este endpoint implementa rotación de tokens refresh por seguridad:

  • Cada refresh genera un NUEVO token refresh
  • El token refresh viejo se invalida
  • Siempre actualiza tu token refresh almacenado

Ejemplos​

curl -X POST https://api.callcov.com/api/v1/auth/refresh \
-H "Content-Type: application/json" \
-d '{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'

Patrón de Auto-Refresh​

Cliente Python con Auto-Refresh​

import requests
from datetime import datetime, timedelta
import threading

class CallCovClient:
    def __init__(self, access_token, refresh_token):
        self.base_url = "https://api.callcov.com/api/v1"
        self.access_token = access_token
        self.refresh_token = refresh_token
        self.token_expiry = datetime.now() + timedelta(minutes=30)
        self.refresh_lock = threading.Lock()

    def refresh_tokens(self):
        """Refrescar tokens de acceso y refresh"""
        with self.refresh_lock:
            response = requests.post(
                f"{self.base_url}/auth/refresh",
                json={"refresh_token": self.refresh_token}
            )

            if response.status_code == 200:
                data = response.json()
                self.access_token = data['access_token']
                self.refresh_token = data['refresh_token']
                self.token_expiry = datetime.now() + timedelta(minutes=30)
                return True
            return False

    def get_headers(self):
        """Obtener headers de autorización, refrescando token si es necesario"""
        # Refrescar si el token expira en menos de 5 minutos
        if datetime.now() + timedelta(minutes=5) >= self.token_expiry:
            if not self.refresh_tokens():
                raise Exception("Error al refrescar token. Por favor inicia sesión de nuevo.")

        return {"Authorization": f"Bearer {self.access_token}"}

    def make_request(self, method, endpoint, **kwargs):
        """Hacer request autenticado con auto-refresh"""
        headers = self.get_headers()
        if 'headers' in kwargs:
            kwargs['headers'].update(headers)
        else:
            kwargs['headers'] = headers

        response = requests.request(
            method,
            f"{self.base_url}{endpoint}",
            **kwargs
        )

        # Si 401, intentar refrescar token una vez y reintentar
        if response.status_code == 401:
            if self.refresh_tokens():
                headers = self.get_headers()
                kwargs['headers'] = headers
                response = requests.request(
                    method,
                    f"{self.base_url}{endpoint}",
                    **kwargs
                )

        return response

# Uso
client = CallCovClient(access_token, refresh_token)

# Refresca automáticamente los tokens cuando es necesario
response = client.make_request('GET', '/users/me')
print(response.json())

Errores​

401 Unauthorized​

Token refresh inválido:

{
  "detail": "Token refresh inválido"
}

Usuario no encontrado o inactivo:

{
  "detail": "Usuario no encontrado o inactivo"
}

Cuándo Refrescar​

Refrescá el token de acceso cuando:

  • El token de acceso ha expirado (la API devuelve 401)
  • El token de acceso va a expirar pronto (refresh preventivo)
  • La aplicación se inicia (verificar si el token está expirado)

Mejores Prácticas​

  1. Refresh Preventivo: Refrescar 5 minutos antes de la expiración
  2. Manejar Fallos: Si el refresh falla, redirigir al login
  3. Actualizar Almacenamiento: Siempre actualizar ambos tokens
  4. Seguridad de Hilos: Usar locks para prevenir intentos de refresh concurrentes
  5. Reintentar Una Vez: Si la API devuelve 401, intentar refrescar y reintentar una vez

Consideraciones de Seguridad​

  • Rotación de token refresh: Cada refresh invalida el token refresh viejo
  • Expiración: Los tokens refresh expiran en 7 días
  • Almacenamiento seguro: Almacenar tokens refresh de forma segura (cookies httpOnly recomendadas)
  • Sin reutilización: Los tokens refresh viejos no pueden reutilizarse

Vida Útil del Token Refresh​

EventoVida Útil
Token creado7 días
Token usado para refreshInmediatamente invalidado, se emite uno nuevo
Token expiradoNo puede refrescarse, el usuario debe iniciar sesión

Relacionado​