Crear clave API

POST /v1/api-keys

Crea una nueva clave API para autenticarse con la API de DocMap. Cada usuario puede tener hasta 10 claves API activas (no revocadas).

Pruébalo

Prueba este endpoint de forma interactiva en la Swagger UI.

Autorización requerida

Incluye tu clave API en el encabezado Authorization.

Solicitud

Encabezados

Encabezado	Valor	Requerido
Authorization	Bearer <token>	Sí
Content-Type	application/json	Sí

Cuerpo

Campo	Tipo	Requerido	Descripción
name	string	Sí	Una etiqueta descriptiva para la clave (1--100 caracteres).
expiresIn	string	Sí	Período de expiración: "30d", "60d", "90d", "1y" o "never".

Ejemplos de código

curl

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

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

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

const { data } = await response.json()

// IMPORTANT: Store the key immediately — it cannot be retrieved later
console.log('API Key:', data.key)
console.log('Key ID:', data.apiKey.id)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

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

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

# IMPORTANT: Store the key immediately — it cannot be retrieved later
print(f"API Key: {data['key']}")
print(f"Key ID: {data['apiKey']['id']}")

Respuesta

Estado: 201 Created

El cuerpo de la respuesta está envuelto en un objeto data.

WARNING

El valor de la clave sin procesar solo se devuelve en esta respuesta. Almacénala de forma segura inmediatamente -- no se puede recuperar después.

Campos

Campo	Tipo	Descripción
key	string	La clave API sin procesar (por ejemplo, dm_live_abc123def456ghi789jkl012mno345). Solo se muestra una vez.
apiKey	object	Objeto de metadatos de la clave (ver abajo).

Objeto apiKey:

Campo	Tipo	Descripción
id	string	Identificador único de la clave API.
userId	string	ID del usuario propietario de la clave.
name	string	Etiqueta descriptiva de la clave.
prefix	string	Primeros caracteres de la clave para identificación (por ejemplo, dm_live_abc1).
expiresAt	string | null	Marca de tiempo ISO 8601 de expiración, o null si la clave nunca expira.
lastUsedAt	string | null	Marca de tiempo ISO 8601 de la última vez que se usó la clave. null si nunca se ha usado.
createdAt	string	Marca de tiempo ISO 8601 de cuándo se creó la clave.
revoked	boolean	Si la clave ha sido revocada. Siempre false para una clave recién creada.

Ejemplo

{
  "data": {
    "key": "dm_live_r4nd0mK3yV4lu3x9w8v7u6t5s4q3p2n1m0l9k8j7",
    "apiKey": {
      "id": "ak_1a2b3c4d5e6f7g8h",
      "userId": "uid_a1b2c3d4e5f6",
      "name": "Production Server",
      "prefix": "dm_live_r4nd",
      "expiresAt": "2025-02-18T10:00:00.000Z",
      "lastUsedAt": null,
      "createdAt": "2024-11-20T10:00:00.000Z",
      "revoked": false
    }
  }
}

Errores

Estado	Código	Descripción
400	MAX_KEYS_REACHED	Has alcanzado el máximo de 10 claves API activas. Revoca una clave existente antes de crear una nueva.
401	UNAUTHORIZED	Clave API / token faltante, inválido o expirado.