La API de Autenticación de Cobre permite un acceso seguro y sin fricciones a la plataforma Cobre Move Money. Autentícate con un user_id y un secret obtenidos desde el Portal de Cobre para recibir un JSON Web Token (JWT) de corta duración en todas las llamadas posteriores a la API.

Guía de la API de Autenticación de Cobre

La API de Autenticación de Cobre facilita interacciones seguras dentro de la plataforma Cobre Money Movement. Sigue esta guía paso a paso para autenticarte y usar los servicios de la plataforma de manera efectiva.

Obtener credenciales de API

Antes de poder autenticarte, necesitas obtener las credenciales de API necesarias: un user_id y un secret. Estas credenciales se proporcionan dentro del ecosistema de Cobre, asegurando una forma segura y directa de acceder a la plataforma.

Autenticarse en la plataforma

Con tus credenciales de API en mano, úsalas para autenticarte en la plataforma. Envía una solicitud al endpoint de la API de Autenticación, incluyendo tu user_id y secret. Tras una autenticación exitosa, la API retorna un JSON Web Token (JWT).

Ejemplo de solicitud de autenticación:

POST /auth
Content-Type: application/json

{
  "user_id": "your_user_id",
  "secret": "your_secret"
}

Ejemplo de respuesta de autenticación:

{
    "access_token": "eyJhbGciOiJSUzI1...",
    "type": "Bearer",
    "expiration_time": 1200
}

¡Comienza a mover dinero!

Con el token JWT en mano, podrás iniciar todas tus operaciones de movimiento de dinero.

Caché de inicio de sesión y ciclo de vida del token

Cobre almacena en caché los tokens de inicio de sesión en el servidor. Cuando llamas al endpoint de Autenticación con las mismas credenciales, Cobre consulta la caché antes de emitir un nuevo token:

Cache hit — retorna el token almacenado en caché; no se genera un nuevo JWT.

Cache miss — genera un nuevo token y lo almacena en la caché.

El TTL de la caché es el 90% de la vida útil del token. Esto crea un margen de seguridad del 10% en el que el JWT sigue siendo válido pero la caché ya expiró, de modo que la siguiente llamada de inicio de sesión siempre obtiene un token nuevo en lugar de servir uno cercano a su expiración.

La vida útil del token en producción es actualmente 1 200 s (20 min). Este valor puede cambiar; todas las proporciones siguientes se mantienen para cualquier expiration_time.

Qué significa `expiration_time` en cada escenario

Escenario	`expiration_time` en la respuesta
Cache miss (primera llamada, o tras expirar el TTL de la caché)	Vida útil completa del token (p. ej. 1 200 s)
Cache hit (0 < T < TTL de la caché)	TTL restante de la caché — no la vida útil restante del JWT

En un cache hit, trata expiration_time como el tiempo restante hasta que debes renovar — no como la expiración absoluta del JWT. Ejemplo: en T + 1 min, puedes recibir 1 020 s aunque el JWT subyacente se haya emitido antes.

Parámetro	Valor (ejemplo con token de 20 min)
Vida útil del token	1 200 s (20 min)
TTL de la caché (90%)	1 080 s (18 min)
Margen de seguridad del 10%	120 s (2 min) — token válido, caché expirada
Renovación recomendada en el cliente (95%)	1 140 s (19 min)

Mejores prácticas de gestión de tokens

Las APIs de Cobre usan tokens de acceso de corta duración, por lo que tu integración debe manejar la renovación de tokens de manera controlada:

No solicites un nuevo token en cada llamada de API. Esto es ineficiente y puede causarte bloqueos debido a la limitación de velocidad.

Almacena el token en caché, reutilízalo y renóvalo solo cuando esté cerca de expirar.

Implementa un único administrador de tokens que compartan todas las solicitudes a las APIs de Cobre.

Esto proporciona:

Menor latencia (menos llamadas de autenticación)

Rendimiento más estable

Manejo de errores y observabilidad más limpios

Mejor resistencia bajo carga

Recomendaciones

Almacena el token en caché del lado del cliente y reutilízalo hasta que expiration_time expire — nunca llames a /v1/auth en cada solicitud.

Renueva al 95% de expiration_time (1 140 s / 19 min para tokens de 20 min). La caché del servidor expira al 90% (18 min), por lo que llamar al 95% siempre ocurre después de que la caché ya expiró — garantizando un token nuevo.

Comparte un token por conjunto de credenciales entre workers — las llamadas paralelas se benefician de la misma entrada de caché.

Almacena tokens en memoria cuando sea posible (más rápido). Si ejecutas múltiples instancias, considera una caché compartida (Redis, Memcached) para que todas las réplicas reutilicen el mismo token.

Implementación de referencia (pseudocódigo independiente del lenguaje)

Usa esta lógica antes de cada solicitud a Cobre:

function getValidToken():
  refresh_at = cached_expires_at - (0.05 * cached_expiration_time)

  if cached_token exists AND now < refresh_at:
      return cached_token

  lock(token_refresh_lock):
      # Double-check after acquiring lock
      if cached_token exists AND now < refresh_at:
          return cached_token

      response = requestNewToken()
      cached_token = response.access_token
      cached_expiration_time = response.expiration_time
      cached_expires_at = now + response.expiration_time
      return cached_token

Si tu sistema hace solicitudes paralelas, usa un lock o mutex para asegurar que solo ocurra una renovación a la vez y que todas las demás solicitudes esperen por ella. Esto evita tormentas de tokens — múltiples renovaciones simultáneas de tokens bajo carga.

Manejo de una respuesta 401

Un 401 en cualquier endpoint de la API de Cobre significa que el encabezado Authorization: Bearer <access_token> falta, está mal formado, o el token ha expirado o ya no es válido — a diferencia de un 403 (token válido, pero sin permisos suficientes sobre ese recurso).

Un 401 debería ser poco frecuente si sigues el patrón de renovación al 95% descrito arriba. Trátalo como una red de seguridad de respaldo, no como tu estrategia principal de gestión de tokens.

Manejo recomendado:

Ante un 401, llama nuevamente a POST /auth con tu user_id/secret para obtener un nuevo token.

Reintenta la solicitud original una sola vez con el nuevo token.

Si el reintento también retorna 401, detén los reintentos — esto indica credenciales inválidas (no un token expirado) y debe tratarse como un fallo definitivo para que alguien verifique el user_id/secret.

Para solicitudes no idempotentes (por ejemplo, crear un Movimiento de Dinero), no reintentes tras renovar el token sin una llave de idempotencia. Si la solicitud original ya fue procesada por Cobre antes de que la respuesta te llegara, un reintento ciego puede generar un duplicado. Reutiliza la misma llave de idempotencia en el reintento.

response = call(endpoint, token)
if response.status == 401:
    token = requestNewToken()
    response = call(endpoint, token, idempotency_key=same_key)
    if response.status == 401:
        raise AuthenticationError("Invalid credentials")

Acciones permitidas en Autenticación

🔑 Autenticar

Descripción: Intercambia tu user_id y secret por un token Bearer de corta duración.

Qué esperar después de la acción: Un JWT con access_token, type y expiration_time.

📘 Más información:

🔗 Autenticación

Cómo empezar

Antes de comenzar, recomendamos tener claridad sobre los pasos preliminares requeridos antes de usar esta solución.

Crea tus credenciales de API desde el Portal

Accede al Portal y encuentra la sección Developers en la parte inferior del menú lateral izquierdo.

Una vez en la sección Developers, haz clic en la pestaña de credenciales de API, luego en + Create Credential.

Aparecerá una nueva ventana. Asigna un alias y selecciona el rol para crear tu credencial de API con el acceso necesario.

Una vez que se genere la credencial, asegúrate de almacenarla en un lugar seguro ya que no será posible obtenerla nuevamente.

Qué esperar después de usar esta API

Usa el JWT en todas las llamadas a las APIs de Cobre

Pasa el token en el encabezado Authorization: Bearer <access_token> en cada solicitud posterior a las APIs de Cobre.

Almacena en caché y renueva según expiration_time

Guarda el token y su timestamp de expiración. Reutiliza el token en caché hasta alcanzar el punto de renovación del 95% descrito en Mejores prácticas de gestión de tokens — no solicites un nuevo token en cada llamada de API de negocio.

Continúa con otras guías de API

Consulta las siguientes secciones para aprender más sobre las APIs de Cobre e integrar flujos de movimiento de dinero.

Conoce la documentación técnica de nuestra API de Autenticación:

API de Autenticación

Obtén tokens de autenticación para comenzar a usar las APIs de Cobre

Autenticación

Guía de la API de Autenticación de Cobre#

Caché de inicio de sesión y ciclo de vida del token#

Qué significa expiration_time en cada escenario#

Mejores prácticas de gestión de tokens#

Recomendaciones#

Implementación de referencia (pseudocódigo independiente del lenguaje)#

Manejo de una respuesta 401#

Acciones permitidas en Autenticación#

Cómo empezar#

Qué esperar después de usar esta API#

Guía de la API de Autenticación de Cobre

Caché de inicio de sesión y ciclo de vida del token

Qué significa `expiration_time` en cada escenario

Mejores prácticas de gestión de tokens

Recomendaciones

Implementación de referencia (pseudocódigo independiente del lenguaje)

Manejo de una respuesta 401

Acciones permitidas en Autenticación

Cómo empezar

Qué esperar después de usar esta API