Autenticación

Descripción general

Todos los endpoints /v1/* requieren autenticación mediante el encabezado Authorization usando un token Bearer:

Authorization: Bearer <token>

Claves API

Las claves API son el método de autenticación recomendado para uso programático y del lado del servidor. Son de larga duración, fáciles de gestionar y no requieren SDKs externos.

Crear una clave API

Puedes crear claves API de dos formas:

Desde el panel de control:

1. Ve a Panel de control > Configuración > Claves API.
2. Haz clic en Crear clave API.
3. Introduce un nombre descriptivo y selecciona un período de expiración.
4. Copia la clave inmediatamente.

Desde la API:

curl -X POST https://api.docmap.io/v1/api-keys \
  -H "Authorization: Bearer <existing-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "expiresIn": "90d"
  }'

Formato de la clave

Las claves API siguen el formato:

dm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Las claves tienen 72 caracteres y siempre comienzan con el prefijo dm_live_.

Opciones de expiración

Al crear una clave, puedes elegir entre estos períodos de expiración:

• 30 días
• 60 días
• 90 días
• 1 año
• Nunca (sin expiración)

WARNING

Las claves que nunca expiran son convenientes pero conllevan un mayor riesgo si se ven comprometidas. Usa la expiración más corta que se ajuste a tus necesidades.

Límites

Cada cuenta puede tener un máximo de 10 claves API activas en cualquier momento. Revoca las claves no utilizadas para liberar espacios.

Ejemplo de solicitud

cURL

curl https://api.docmap.io/v1/extractions \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch('https://api.docmap.io/v1/extractions', {
  headers: {
    'Authorization': `Bearer ${process.env.DOCMAP_API_KEY}`,
  },
})

Respuestas de error

Si la autenticación falla, la API devuelve una respuesta 401 Unauthorized:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token."
  }
}

Causas comunes:

• Falta el encabezado Authorization
• Token mal formado (prefijo o formato incorrecto)
• Clave API expirada
• Clave API revocada

Mejores prácticas de seguridad

DANGER

Nunca expongas claves API en código del lado del cliente, repositorios públicos o entornos de navegador. Las claves API otorgan acceso completo a la API de tu cuenta y deben tratarse como secretos.

Sigue estas directrices para mantener tus credenciales de API seguras:

1. Almacena las claves en variables de entorno -- Nunca codifiques claves API directamente en el código fuente. Usa variables de entorno o un gestor de secretos.

   # .env file (never commit this)
   DOCMAP_API_KEY=dm_live_your_api_key

   // Read from environment
   const apiKey = process.env.DOCMAP_API_KEY

2. Rota las claves periódicamente -- Crea nuevas claves y retira las antiguas de forma regular, incluso si no tienes razones para sospechar que se han comprometido.

3. Revoca las claves comprometidas inmediatamente -- Si una clave se expone accidentalmente (por ejemplo, se sube a un repositorio público), revócala en Panel de control > Configuración > Claves API de inmediato y crea una nueva.

4. Usa la expiración más corta razonable -- Elige un período de expiración que equilibre la comodidad con la seguridad. Para la mayoría de los casos de uso en producción, 90 días es un buen valor predeterminado.

5. Usa claves separadas para diferentes entornos -- Crea claves distintas para desarrollo, staging y producción. Esto limita el radio de impacto si una clave se ve comprometida y facilita la rotación de claves sin tiempo de inactividad.

6. Añade tu archivo .env a .gitignore -- Asegúrate de que tus archivos de entorno nunca se suban al control de versiones.

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