Gestión de claves API

Descripción general

Las claves API proporcionan acceso programático a la API de DocMap. Cada clave es un token de 72 caracteres con el prefijo dm_live_ que se pasa como token Bearer en el encabezado Authorization.

Datos clave:

Máximo 10 claves activas por cuenta
Formato: dm_live_ seguido de 64 caracteres hexadecimales aleatorios (72 caracteres en total)
Las claves se hashean antes de almacenarse -- la clave sin procesar solo se muestra una vez en el momento de la creación
Las claves pueden tener fechas de expiración o configurarse para que nunca expiren

Crear una clave

Desde el panel de control

Navega a Configuración > Claves API en tu panel de control de DocMap
Haz clic en Crear clave API
Introduce un nombre descriptivo (por ejemplo, "Servidor de producción", "Pipeline CI/CD")
Selecciona un período de expiración
Copia la clave mostrada inmediatamente -- no se volverá a mostrar

Desde la API

También puedes crear claves de forma programática autenticándote con una clave API existente:

curlTypeScriptPython

bash

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

typescript

const response = await fetch("https://api.docmap.io/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${existingApiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Production Server",
    expiresIn: "90d",
  }),
});

const { data } = await response.json();

// Store this immediately -- it will never be shown again
console.log("API Key:", data.key);
console.log("Key ID:", data.apiKey.id);

python

import requests

response = requests.post(
    "https://api.docmap.io/v1/api-keys",
    headers={
        "Authorization": f"Bearer {existing_api_key}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Production Server",
        "expiresIn": "90d",
    },
)

data = response.json()["data"]

# Store this immediately -- it will never be shown again
print("API Key:", data["key"])
print("Key ID:", data["apiKey"]["id"])

Valores disponibles de expiresIn:

Valor	Duración
`30d`	30 días
`60d`	60 días
`90d`	90 días
`1y`	1 año
`never`	Sin expiración

La respuesta incluye tanto la clave sin procesar como los metadatos de la clave:

json

{
  "data": {
    "key": "dm_live_a1b2c3d4e5f6...",
    "apiKey": {
      "id": "key-abc123",
      "userId": "user_789",
      "name": "Production Server",
      "prefix": "dm_live_a1b2c3d4",
      "expiresAt": "2025-10-13T12:00:00.000Z",
      "lastUsedAt": null,
      "createdAt": "2025-07-15T12:00:00.000Z",
      "revoked": false
    }
  }
}

WARNING

El campo key en la respuesta es la única vez que se devuelve la clave API sin procesar. Almacénala en un lugar seguro (por ejemplo, variable de entorno, gestor de secretos) inmediatamente. Si la pierdes, necesitarás crear una nueva clave.

Listar claves

Recupera todas las claves API activas (no revocadas) de tu cuenta:

curlTypeScriptPython

bash

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

typescript

const response = await fetch("https://api.docmap.io/v1/api-keys", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await response.json();

data.forEach((key) => {
  console.log(`${key.name} (${key.prefix}...) - Last used: ${key.lastUsedAt ?? "Never"}`);
});

python

response = requests.get(
    "https://api.docmap.io/v1/api-keys",
    headers={"Authorization": f"Bearer {api_key}"},
)

for key in response.json()["data"]:
    last_used = key["lastUsedAt"] or "Never"
    print(f"{key['name']} ({key['prefix']}...) - Last used: {last_used}")

La respuesta incluye metadatos de cada clave pero nunca el valor completo de la clave -- solo se muestra el prefix (primeros 16 caracteres):

json

{
  "data": [
    {
      "id": "key-abc123",
      "userId": "user_789",
      "name": "Production Server",
      "prefix": "dm_live_a1b2c3d4",
      "expiresAt": "2025-10-13T12:00:00.000Z",
      "lastUsedAt": "2025-07-15T14:30:00.000Z",
      "createdAt": "2025-07-15T12:00:00.000Z",
      "revoked": false
    }
  ]
}

Rotar claves

Para rotar una clave API sin tiempo de inactividad, sigue estos pasos:

Crea una nueva clave con un nombre descriptivo que indique que es un reemplazo
Actualiza tus sistemas (variables de entorno, gestor de secretos, CI/CD) para usar la nueva clave
Verifica que la nueva clave funciona correctamente haciendo una llamada de prueba a la API
Revoca la clave antigua una vez que todos los sistemas hayan sido actualizados

typescript

// Step 1: Create the new key
const createResponse = await fetch("https://api.docmap.io/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${currentApiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Production Server (rotated 2025-07)",
    expiresIn: "90d",
  }),
});

const { data: newKeyData } = await createResponse.json();
const newKey = newKeyData.key;

// Step 2: Verify the new key works
const testResponse = await fetch("https://api.docmap.io/v1/usage", {
  headers: { Authorization: `Bearer ${newKey}` },
});

if (testResponse.ok) {
  console.log("New key verified. Update your environment variables now.");

  // Step 3: Revoke the old key (after updating systems)
  // await fetch(`https://api.docmap.io/v1/api-keys/${oldKeyId}`, {
  //   method: "DELETE",
  //   headers: { Authorization: `Bearer ${newKey}` },
  // });
}

TIP

Mantén ambas claves activas durante el período de transición. Solo revoca la clave antigua después de confirmar que todos los sistemas están usando la nueva.

Revocar claves

Revoca una clave API enviando una solicitud DELETE con el ID de la clave. La clave deja de funcionar inmediatamente.

curlTypeScriptPython

bash

curl -X DELETE https://api.docmap.io/v1/api-keys/key-abc123 \
  -H "Authorization: Bearer dm_live_your_api_key"

typescript

const response = await fetch("https://api.docmap.io/v1/api-keys/key-abc123", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${apiKey}` },
});

const result = await response.json();
console.log("Revoked:", result.success); // true

python

response = requests.delete(
    "https://api.docmap.io/v1/api-keys/key-abc123",
    headers={"Authorization": f"Bearer {api_key}"},
)

print("Revoked:", response.json()["success"])  # True

WARNING

La revocación es inmediata y permanente. Cualquier solicitud que use la clave revocada recibirá un error 401 UNAUTHORIZED. Asegúrate de que ningún sistema activo dependa de la clave antes de revocarla.

Monitoreo de uso

Cada clave API registra una marca de tiempo lastUsedAt que se actualiza automáticamente cada vez que la clave se usa para autenticar una solicitud. Usa el endpoint de listado para monitorear cuándo se usaron por última vez tus claves:

typescript

const response = await fetch("https://api.docmap.io/v1/api-keys", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data: keys } = await response.json();

// Find keys that haven't been used in over 30 days
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);

keys.forEach((key) => {
  if (!key.lastUsedAt || new Date(key.lastUsedAt) < thirtyDaysAgo) {
    console.log(`Key "${key.name}" (${key.prefix}...) is inactive — consider revoking it`);
  }
});

Mejores prácticas

Usa nombres descriptivos. Nombra las claves según su propósito o entorno: "API de producción", "Staging", "GitHub Actions CI". Esto facilita identificar qué clave revocar si alguna se ve comprometida.
Establece fechas de expiración. Prefiere 90d o 1y en lugar de never. Las claves con expiración obligan a una rotación regular, lo que limita la ventana de exposición si una clave se filtra.
Separa los entornos. Usa diferentes claves para desarrollo, staging y producción. Nunca compartas una clave entre entornos.
Rota regularmente. Incluso con fechas de expiración, rota las claves de forma proactiva -- especialmente después de que miembros del equipo se vayan o la infraestructura cambie.
Nunca registres claves sin procesar. Evita imprimir claves API en logs de aplicación, informes de errores o salida de consola. Usa el campo prefix cuando necesites referenciar una clave en los logs.
Usa variables de entorno. Almacena las claves en variables de entorno o un gestor de secretos. Nunca las codifiques directamente en el código fuente ni las subas al control de versiones.

Gestión de claves API ​

Descripción general ​

Crear una clave ​

Desde el panel de control ​

Desde la API ​

Listar claves ​

Rotar claves ​

Revocar claves ​

Monitoreo de uso ​

Mejores prácticas ​

Gestión de claves API

Descripción general

Crear una clave

Desde el panel de control

Desde la API

Listar claves

Rotar claves

Revocar claves

Monitoreo de uso

Mejores prácticas