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

POST /v1/api-keys

Создание нового API-ключа для аутентификации с DocMap API. Каждый пользователь может иметь до 10 активных (не отозванных) API-ключей.

Попробуйте

Протестируйте этот эндпоинт интерактивно в Swagger UI.

Требуется авторизация

Укажите ваш API-ключ в заголовке Authorization.

Запрос

Заголовки

Заголовок	Значение	Обязательно
Authorization	Bearer <token>	Да
Content-Type	application/json	Да

Тело запроса

Поле	Тип	Обязательно	Описание
name	string	Да	Описательная метка для ключа (1--100 символов).
expiresIn	string	Да	Срок действия: "30d", "60d", "90d", "1y" или "never".

Примеры кода

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

Ответ

Статус: 201 Created

Тело ответа обернуто в объект data.

WARNING

Значение ключа в открытом виде возвращается только в этом ответе. Сохраните его в безопасном месте немедленно -- позже его нельзя будет получить.

Поля

Поле	Тип	Описание
key	string	API-ключ в открытом виде (например, dm_live_abc123def456ghi789jkl012mno345). Показывается только один раз.
apiKey	object	Объект метаданных ключа (см. ниже).

Объект apiKey:

Поле	Тип	Описание
id	string	Уникальный идентификатор API-ключа.
userId	string	ID пользователя, которому принадлежит ключ.
name	string	Описательная метка ключа.
prefix	string	Первые символы ключа для идентификации (например, dm_live_abc1).
expiresAt	string | null	Временная метка ISO 8601 истечения срока действия, или null, если ключ бессрочный.
lastUsedAt	string | null	Временная метка ISO 8601 последнего использования ключа. null, если никогда не использовался.
createdAt	string	Временная метка ISO 8601 создания ключа.
revoked	boolean	Был ли ключ отозван. Для вновь созданного ключа всегда false.

Пример

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

Ошибки

Статус	Код	Описание
400	MAX_KEYS_REACHED	Вы достигли максимума в 10 активных API-ключей. Отзовите существующий ключ перед созданием нового.
401	UNAUTHORIZED	Отсутствующий, недействительный или просроченный API-ключ / токен.