Integraciones seguras

Tokens de acceso y autenticación

Aprende a emitir, rotar y proteger tokens para consumir la API de Be CMS desde distintos lenguajes. Estos ejemplos cubren buenas prácticas de seguridad, monitoreo y automatización para escalar sin fricción.

OAuth 2.1 readyScopes granularesCompatibilidad multi-stack

Fundamentos

Conceptos base

Los tokens firmados permiten autenticar integraciones server-to-server y clientes privilegiados. Se emiten desde el panel de Be CMS o vía API y poseen expiración configurable para adaptarse a tus flujos.

Tipos de credenciales

Tokens de servicio: ideales para sincronizaciones programadas y bots internos.
Tokens efímeros: válidos por minutos para acciones puntuales dentro del CMS.
Tokens impersonados: permiten actuar en nombre de un usuario con auditoría completa.

Flujo recomendado

Crea un token desde el panel o la API con los scopes mínimos necesarios.
Almacénalo cifrado en tu gestor de secretos (Vault, Parameter Store, etc.).
Renueva automáticamente antes de su expiración usando webhooks o cron jobs.

Fundamentos

Scopes y roles

Define permisos granulares para cada integración. Los scopes se agrupan por dominio funcional y pueden combinarse en un mismo token para cubrir distintos casos de uso.

Scope	Descripción	Uso sugerido
content:write	Permite crear, actualizar y publicar entradas en colecciones configuradas.	Automatizaciones editoriales.
catalog:read	Consulta catálogos, taxonomías y relaciones entre colecciones.	Frontends headless y microservicios.
assets:write	Gestiona la subida y transformación de activos multimedia.	Pipelines de media y DAM externos.
events:write	Emite eventos personalizados para disparar automatizaciones o integraciones.	Integraciones con CRM o CDP.

Consulta la lista completa de scopes en la sección de fundamentos para adaptar tus flujos.

Implementaciones

JavaScript (Node.js)

Usa fetch o Axios para intercambiar tus credenciales y recibir un token firmado compatible con nuestras APIs REST y GraphQL.

import fetch from 'node-fetch'

async function generateToken() {
  const response = await fetch('https://cms.begraffic.com/v1/tokens', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Workspace-Id': process.env.BE_WORKSPACE_ID ?? '',
      Authorization: `Bearer ${process.env.BE_CLIENT_SECRET}`,
    },
    body: JSON.stringify({
      name: 'CLI de despliegue',
      scopes: ['content:write', 'catalog:read'],
      ttl: 60 * 60, // 1 hora
    }),
  })

  if (!response.ok) {
    throw new Error('No se pudo generar el token')
  }

  const payload = await response.json()
  return payload.token
}

generateToken().then(console.log).catch(console.error)

Implementaciones

Python

Integra los tokens en scripts de automatización o cron jobs utilizando requests y manejo seguro de variables.

import os
import requests

API_URL = 'https://cms.begraffic.com/v1/tokens'

def create_token():
    response = requests.post(
        API_URL,
        headers={
            'Content-Type': 'application/json',
            'X-Workspace-Id': os.environ['BE_WORKSPACE_ID'],
            'Authorization': f"Bearer {os.environ['BE_CLIENT_SECRET']}",
        },
        json={
            'name': 'sync-crm',
            'scopes': ['users:read', 'events:write'],
            'ttl': 900,
        },
        timeout=10,
    )

    response.raise_for_status()
    return response.json()['token']

if __name__ == '__main__':
    token = create_token()
    print('Token listo:', token)

Implementaciones

Go

Aprovecha el cliente HTTP nativo y el contexto para trabajar con expiraciones y cancelaciones.

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"
)

type tokenResponse struct {
    Token string `json:"token"`
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    body, _ := json.Marshal(map[string]interface{}{
        "name":   "go-worker",
        "scopes": []string{"catalog:write", "assets:read"},
        "ttl":    1800,
    })

    req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://cms.begraffic.com/v1/tokens", bytes.NewReader(body))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Workspace-Id", os.Getenv("BE_WORKSPACE_ID"))
    req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BE_CLIENT_SECRET")))

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    if res.StatusCode >= 400 {
        panic("no se pudo generar el token")
    }

    var payload tokenResponse
    json.NewDecoder(res.Body).Decode(&payload)
    fmt.Println("Token:", payload.Token)
}

Buenas prácticas

Rotación segura

Mantén el ciclo de vida de tus tokens bajo control para evitar accesos no autorizados. Estas recomendaciones te ayudan a estandarizar procesos sin sacrificar velocidad.

Programa la rotación automática cada 30 días o menos para integraciones críticas.
Registra todos los tokens emitidos con propósito, responsable y fecha de expiración.
Utiliza scopes específicos en lugar de otorgar permisos globales para minimizar el riesgo.
Apóyate en webhooks de expiración para renovar credenciales sin interrupciones.

Buenas prácticas

Testing y monitoreo

Complementa la implementación con observabilidad. Monitorea el consumo, los errores y la exposición de los tokens para reaccionar rápidamente ante anomalías.

Testing de integración

Valida que cada nueva versión del token respete los scopes necesarios mediante suites automáticas en tu pipeline CI/CD.

Alertas proactivas

Configura métricas de error rate y latencias asociadas a endpoints protegidos. Usa umbrales distintos para tráfico interno y externo.

Inventario de credenciales

Centraliza la emisión, revocación y auditoría en tu plataforma IAM preferida conectando nuestros webhooks.