Autenticación

Todo sobre como autenticar tus requests a pan API

pan API soporta múltiples métodos de autenticación para diferentes casos de uso. Esta guía cubre todos los métodos disponibles, cuando usar cada uno, y mejores prácticas de seguridad.

Métodos de Autenticación

API Key

Autenticación principal para integraciones servidor-a-servidor

X402 Protocol

Pago por uso sin necesidad de cuenta (solo lectura)

Stack Auth

Autenticación de usuarios para el dashboard

API Key (Recomendado)

La autenticación por API Key es el método principal y recomendado para la mayoria de las integraciones.

1. Request

   Tu app envia request con header Authorization: Bearer pan_sk_xxx

2. Validación

   pan válida la API key y verifica el plan del developer

3. Creditos

   Se deduce 1 crédito del balance

4. Response

   Respuesta incluye header x-credits-remaining con créditos restantes

Formato de API Key

Las API keys de pan tienen el siguiente formato:

pan_sk_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

• Prefijo: pan_sk_ (identifica qué es una key de pan)
• Cuerpo: 64 caracteres hexadecimales (256 bits de entropía)

Como Usar

Incluye tu API key en el header Authorization de cada request:

cURL

curl -X GET https://api.pan.tech/v1/wallets/user_123 \
  -H "Authorization: Bearer pan_sk_tu_api_key_aqui"

Obtener tu API Key

1. Inicia sesion en app.pan.tech
2. Navega a Settings > API Keys
3. Click en Create New Key
4. Copia la key inmediatamente (solo se muestra una vez)

Guarda tu API key de forma segura. No podras verla de nuevo después de cerrar el modal. Si la pierdes, deberas crear una nueva.

Múltiples API Keys

Puedes crear múltiples API keys para diferentes propositos:

Uso	Recomendacion
Desarrollo	Key separada con prefijo dev_ en metadata
Staging	Key separada con acceso limitado
Produccion	Key principal, bien protegida
CI/CD	Key con permisos minimos necesarios

// Ejemplo: usar diferentes keys por entorno
const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.PAN_API_KEY_PROD
  : process.env.PAN_API_KEY_DEV;

const pan = new Pan({ apiKey });

Revocar API Keys

Si sospechas que tu API key fue comprometida:

1. Ve a Settings > API Keys en el dashboard
2. Encuentra la key comprometida
3. Click en Revoke
4. Crea una nueva key
5. Actualiza tu aplicación con la nueva key

Las keys revocadas dejan de funcionar inmediatamente. Asegurate de tener la nueva key lista antes de revocar la anterior.

Créditos y Facturación

Cada request a pan API consume créditos de tu cuenta:

Endpoint	Créditos
POST /wallets	1
GET /wallets/:id	1
GET /balances/:id	1
GET /yields	1
POST /intents	5
GET /intents/:id	1

Planes y Limites

Free

• 100 creditos/mes
• 100 wallets max
• Solo testnets

Pro

• 10,000 creditos/mes
• 10,000 wallets max
• Mainnet habilitado

Enterprise

• Créditos ilimitados
• Wallets ilimitadas
• SLA dedicado

Verificar Créditos Restantes

curl -X GET https://api.pan.tech/dashboard/credits \
  -H "Authorization: Bearer $PAN_API_KEY"

{
  "balance": 8750,
  "totalPurchased": 10000,
  "totalUsed": 1250,
  "plan": "pro",
  "resetsAt": "2024-02-01T00:00:00Z"
}

X402 Protocol (Pago por Uso)

X402 es un protocolo de micropagos que permite usar la API sin crear una cuenta, pagando por cada request.

Cuando Usar X402

Usar X402

• Integraciones de prueba rapida
• Acceso anonimo a la API
• Endpoints de solo lectura
• Cuando no quieres manejar API keys

No Usar X402

• Operaciones de escritura (crear wallets, intents)
• Produccion con alto volumen
• Cuando necesitas tracking detallado

Como Funcióna

1. Precio: Cada request cuesta $0.001 USD
2. Pago: Se realiza en USDC en las redes soportadas (Base, Ethereum, Sei)
3. Prueba: Incluyes un proof de pago en el header X-Payment-Proof

Endpoints Soportados

Solo endpoints de lectura soportan X402:

Endpoint	X402
GET /wallets/:userId	Si
GET /balances/:walletId	Si
GET /yields	Si
GET /intents/:intentId	Si
POST /wallets	No
POST /intents	No

Ejemplo de Uso

import { X402Client } from 'x402-client';

const x402 = new X402Client({
  network: 'base',
  wallet: yourWallet // wallet con USDC
});

// El cliente X402 maneja el pago automaticamente
const response = await x402.fetch('https://api.pan.tech/v1/yields');
const yields = await response.json();

X402 no está disponible para operaciones de escritura. Para crear wallets o intents, debes usar API Key.

Stack Auth (Dashboard)

Stack Auth se usa exclusivamente para autenticar usuarios en el dashboard web de pan.

Flujo de Autenticación

1. Usuario visita dashboard

   Accede a app.pan.tech

2. Redirección a Stack Auth

   El dashboard redirige al formulario de login

3. Usuario ingresa credenciales

   Stack Auth válida el usuario

4. Sesion creada

   Stack Auth retorna token, dashboard crea sesion y carga

No Usar para API

Stack Auth no es para llamadas programaticas a la API. Usa siempre API Key para integraciones servidor-a-servidor.

Seguridad: Mejores Practicas

1. Nunca Expongas tu API Key

MAL

// En el frontend - NUNCA hagas esto
const pan = new Pan({
  apiKey: 'pan_sk_abc123...'
});

BIEN

// En el backend
const pan = new Pan({
  apiKey: process.env.PAN_API_KEY
});

2. Usa Variables de Entorno

# .env (nunca commitear este archivo)
PAN_API_KEY=pan_sk_tu_api_key_aqui

// Tu codigo
const apiKey = process.env.PAN_API_KEY;

3. Agrega .env a .gitignore

# .gitignore
.env
.env.local
.env.*.local

4. Usa Secretos en CI/CD

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        env:
          PAN_API_KEY: ${{ secrets.PAN_API_KEY }}
        run: |
          npm run deploy

5. Rota Keys Periodicamente

Recomendamos rotar tus API keys cada 90 dias:

1. Crea una nueva key
2. Actualiza tu aplicación para usar la nueva key
3. Verifica que todo funcione
4. Revoca la key anterior

6. Monitorea Uso Inusual

Revisa el dashboard periódicamente para detectar:

• Picos de uso inesperados
• Requests desde IPs desconocidas
• Patrones de uso anomalos

7. Usa Keys Diferentes por Entorno

// config.js
const config = {
  development: {
    apiKey: process.env.PAN_API_KEY_DEV,
    baseUrl: 'https://api-staging.pan.tech/v1'
  },
  production: {
    apiKey: process.env.PAN_API_KEY_PROD,
    baseUrl: 'https://api.pan.tech/v1'
  }
};

export default config[process.env.NODE_ENV];

Manejo de Errores de Autenticación

Error 401: Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Causas comunes:

• API key faltante en el header
• API key mal formateada
• API key revocada

Solución:

// Verifica que el header este correcto
headers: {
  'Authorization': `Bearer ${apiKey}` // Nota el espacio después de "Bearer"
}

Error 403: Forbidden

{
  "error": "FORBIDDEN",
  "message": "Wallet limit exceeded for your plan"
}

Causas comunes:

• Excediste el límite de wallets de tu plan
• Intentas acceder a mainnet con plan free
• API key no tiene permisos para está operación

Solución:

• Actualiza tu plan
• Revisa los límites de tu cuenta

Error 429: Rate Limited

{
  "error": "RATE_LIMITED",
  "message": "Too many requests"
}

Headers de respuesta:

Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642248000

Solución:

// Implementa exponential backoff
async function requestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.headers.get('Retry-After') || 60;
        await new Promise(r => setTimeout(r, retryAfter * 1000));
      } else {
        throw error;
      }
    }
  }
}

Próximos Pasos

Crear Wallets

Aprende a crear y gestionar wallets

Ejecutar Intents

Ejecuta tu primera operación DeFi

Seguridad

Guía completa de seguridad

Referencia API

Documentación completa de endpoints