Управление API-ключами

Обзор

API-ключи обеспечивают программный доступ к DocMap API. Каждый ключ представляет собой 72-символьный токен с префиксом dm_live_, который передается как Bearer-токен в заголовке Authorization.

Основные факты:

Максимум 10 активных ключей на аккаунт
Формат: dm_live_ + 64 случайных шестнадцатеричных символа (72 символа всего)
Ключи хешируются перед хранением -- открытый ключ показывается только один раз при создании
Ключи могут иметь срок действия или быть бессрочными

Создание ключа

Через панель управления

Перейдите в Настройки > API-ключи в панели управления DocMap
Нажмите Создать API-ключ
Введите описательное имя (например, "Production Server", "CI/CD Pipeline")
Выберите срок действия
Скопируйте отображаемый ключ немедленно -- он больше не будет показан

Через API

Вы также можете создавать ключи программно, аутентифицируясь с помощью существующего API-ключа:

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"])

Доступные значения expiresIn:

Значение	Срок
`30d`	30 дней
`60d`	60 дней
`90d`	90 дней
`1y`	1 год
`never`	Бессрочный

Ответ содержит как открытый ключ, так и метаданные ключа:

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

Поле key в ответе -- это единственный раз, когда возвращается открытый API-ключ. Сохраните его в безопасном месте (например, переменная окружения, менеджер секретов) немедленно. Если вы его потеряете, вам придется создать новый ключ.

Получение списка ключей

Получите все активные (не отозванные) API-ключи для вашего аккаунта:

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}")

Ответ содержит метаданные для каждого ключа, но никогда не содержит полное значение ключа -- показывается только prefix (первые 16 символов):

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
    }
  ]
}

Ротация ключей

Для ротации API-ключа без простоев выполните следующие шаги:

Создайте новый ключ с описательным именем, указывающим на замену
Обновите свои системы (переменные окружения, менеджер секретов, CI/CD) для использования нового ключа
Проверьте, что новый ключ работает корректно, выполнив тестовый API-вызов
Отзовите старый ключ, когда все системы будут обновлены

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

Держите оба ключа активными в период перехода. Отзывайте старый ключ только после того, как убедитесь, что все системы используют новый.

Отзыв ключей

Отзовите API-ключ, отправив DELETE-запрос с ID ключа. Ключ перестает работать немедленно.

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

Отзыв является немедленным и необратимым. Любой запрос с отозванным ключом получит ошибку 401 UNAUTHORIZED. Убедитесь, что ни одна активная система не зависит от ключа, прежде чем его отзывать.

Мониторинг использования

Каждый API-ключ отслеживает временную метку lastUsedAt, которая автоматически обновляется при каждом использовании ключа для аутентификации запроса. Используйте эндпоинт списка для мониторинга последней активности ключей:

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`);
  }
});

Лучшие практики

Используйте описательные имена. Называйте ключи в соответствии с их назначением или окружением: "Production API", "Staging", "GitHub Actions CI". Это упрощает определение того, какой ключ отозвать в случае компрометации.
Устанавливайте сроки действия. Предпочитайте 90d или 1y вместо never. Ключи с ограниченным сроком действия обеспечивают регулярную ротацию, что ограничивает окно уязвимости при утечке ключа.
Разделяйте окружения. Используйте разные ключи для разработки, тестирования и продакшена. Никогда не используйте один ключ в разных окружениях.
Регулярно ротируйте. Даже при наличии сроков действия, ротируйте ключи проактивно -- особенно после ухода членов команды или изменения инфраструктуры.
Никогда не логируйте открытые ключи. Избегайте вывода API-ключей в логи приложений, отчеты об ошибках или консольный вывод. Используйте поле prefix, когда нужно сослаться на ключ в логах.
Используйте переменные окружения. Храните ключи в переменных окружения или менеджере секретов. Никогда не записывайте их непосредственно в исходный код и не коммитьте в систему контроля версий.

Управление API-ключами ​

Обзор ​

Создание ключа ​

Через панель управления ​

Через API ​

Получение списка ключей ​

Ротация ключей ​

Отзыв ключей ​

Мониторинг использования ​

Лучшие практики ​

Управление API-ключами

Обзор

Создание ключа

Через панель управления

Через API

Получение списка ключей

Ротация ключей

Отзыв ключей

Мониторинг использования

Лучшие практики