Skip to main content

Métodos de autenticación

NotMeta utiliza autenticación basada en tokens JWT (JSON Web Tokens) para garantizar la seguridad de las comunicaciones con la API.

Tipos de tokens

Token de API

El token de API es el método principal de autenticación para aplicaciones:
  • Duración: Configurable (1 día a 1 año)
  • Permisos: Granular por funcionalidad
  • Uso: Recomendado para integraciones
  • Renovación: Manual

Token de sesión

Token temporal para sesiones de usuario:
  • Duración: 24 horas
  • Permisos: Basados en el usuario
  • Uso: Interfaz web y aplicaciones móviles
  • Renovación: Automática

Generar token de API

Desde el panel web

  1. Inicia sesión en NotMeta
  2. Ve a “Configuración” > “API”
  3. Haz clic en “Generar nuevo token”
  4. Configura los permisos necesarios
  5. Copia y guarda el token de forma segura

Desde la API

curl -X POST "https://api.notmeta.com/v1/auth/tokens" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi aplicación",
    "permissions": ["messages:read", "messages:write"],
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Uso del token

Header de autorización

Incluye el token en el header Authorization:
curl -X GET "https://api.notmeta.com/v1/conversations" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

En diferentes lenguajes

JavaScript

const response = await fetch('https://api.notmeta.com/v1/conversations', {
  headers: {
    'Authorization': `Bearer ${process.env.NOTMETA_API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

Python

import requests

headers = {
    'Authorization': f'Bearer {api_token}',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.notmeta.com/v1/conversations', headers=headers)

PHP

$headers = [
    'Authorization: Bearer ' . $api_token,
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.notmeta.com/v1/conversations');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);

Permisos y scopes

Conversaciones

  • conversations:read - Leer conversaciones
  • conversations:write - Crear y modificar conversaciones
  • conversations:delete - Eliminar conversaciones

Mensajes

  • messages:read - Leer mensajes
  • messages:write - Enviar mensajes
  • messages:delete - Eliminar mensajes

Usuarios

  • users:read - Leer información de usuarios
  • users:write - Crear y modificar usuarios
  • users:delete - Eliminar usuarios

Reportes

  • reports:read - Acceder a reportes y métricas

Webhooks

  • webhooks:read - Leer configuración de webhooks
  • webhooks:write - Crear y modificar webhooks
  • webhooks:delete - Eliminar webhooks

Configuración

  • config:read - Leer configuración
  • config:write - Modificar configuración

Verificación de permisos

Verificar token

curl -X GET "https://api.notmeta.com/v1/auth/verify" \
  -H "Authorization: Bearer TU_TOKEN"
Respuesta:
{
  "valid": true,
  "token_type": "api",
  "permissions": ["conversations:read", "messages:write"],
  "expires_at": "2024-12-31T23:59:59Z",
  "created_at": "2024-01-01T00:00:00Z"
}

Verificar permisos específicos

async function hasPermission(token, permission) {
  const response = await fetch('https://api.notmeta.com/v1/auth/verify', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  
  const data = await response.json();
  return data.permissions.includes(permission);
}

// Uso
const canSendMessages = await hasPermission(token, 'messages:write');

Renovación de tokens

Verificar expiración

function isTokenExpired(token) {
  try {
    const payload = JSON.parse(atob(token.split('.')[1]));
    return payload.exp * 1000 < Date.now();
  } catch (error) {
    return true;
  }
}

Renovar token

curl -X POST "https://api.notmeta.com/v1/auth/refresh" \
  -H "Authorization: Bearer TOKEN_ACTUAL" \
  -H "Content-Type: application/json"

Autenticación OAuth (Futuro)

Flujo de autorización

Configuración OAuth

const oauthUrl = `https://api.notmeta.com/oauth/authorize?` +
  `client_id=${CLIENT_ID}&` +
  `redirect_uri=${REDIRECT_URI}&` +
  `scope=${SCOPES}&` +
  `response_type=code&` +
  `state=${RANDOM_STATE}`;

Mejores prácticas de seguridad

Almacenamiento seguro

// ❌ Incorrecto - Token en código
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

// ✅ Correcto - Token en variables de entorno
const token = process.env.NOTMETA_API_TOKEN;

Rotación de tokens

class TokenManager {
  constructor() {
    this.token = null;
    this.refreshToken = null;
    this.expiresAt = null;
  }
  
  async getValidToken() {
    if (!this.token || this.isExpired()) {
      await this.refreshToken();
    }
    return this.token;
  }
  
  isExpired() {
    return this.expiresAt && Date.now() >= this.expiresAt;
  }
  
  async refreshToken() {
    // Implementar lógica de renovación
  }
}

Manejo de errores de autenticación

async function makeAuthenticatedRequest(url, options = {}) {
  try {
    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${await tokenManager.getValidToken()}`
      }
    });
    
    if (response.status === 401) {
      // Token inválido o expirado
      await tokenManager.refreshToken();
      // Reintentar con nuevo token
      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          'Authorization': `Bearer ${await tokenManager.getValidToken()}`
        }
      });
    }
    
    return response;
  } catch (error) {
    console.error('Error de autenticación:', error);
    throw error;
  }
}

Solución de problemas

Error 401: Unauthorized

  • Verifica que el token sea correcto
  • Confirma que el token no haya expirado
  • Revisa los permisos del token

Error 403: Forbidden

  • Verifica que el token tenga los permisos necesarios
  • Confirma que la acción esté permitida para tu rol

Token expirado

  • Implementa renovación automática
  • Maneja graciosamente la expiración
  • Considera usar tokens de larga duración para aplicaciones

Recursos adicionales

Configuración inicial

Configura tu entorno de desarrollo

Webhooks

Configura notificaciones en tiempo real