Create API Key

POST /v1/api-keys

Create a new API key for authenticating with the DocMap API. Each user can have up to 10 active (non-revoked) API keys.

Try it

Test this endpoint interactively in the Swagger UI.

Authorization required

Include your API key in the Authorization header.

Request

Headers

Header	Value	Required
Authorization	Bearer <token>	Yes
Content-Type	application/json	Yes

Body

Field	Type	Required	Description
name	string	Yes	A descriptive label for the key (1--100 characters).
expiresIn	string	Yes	Expiration period: "30d", "60d", "90d", "1y", or "never".

Code Examples

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

Response

Status: 201 Created

The response body is wrapped in a data object.

WARNING

The raw key value is only returned in this response. Store it securely immediately -- it cannot be retrieved later.

Fields

Field	Type	Description
key	string	The raw API key (e.g., dm_live_abc123def456ghi789jkl012mno345). Only shown once.
apiKey	object	Key metadata object (see below).

apiKey object:

Field	Type	Description
id	string	Unique identifier for the API key.
userId	string	ID of the user who owns the key.
name	string	Descriptive label for the key.
prefix	string	First characters of the key for identification (e.g., dm_live_abc1).
expiresAt	string | null	ISO 8601 expiration timestamp, or null if the key never expires.
lastUsedAt	string | null	ISO 8601 timestamp of the last time the key was used. null if never used.
createdAt	string	ISO 8601 timestamp of when the key was created.
revoked	boolean	Whether the key has been revoked. Always false for a newly created key.

Example

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

Errors

Status	Code	Description
400	MAX_KEYS_REACHED	You have reached the maximum of 10 active API keys. Revoke an existing key before creating a new one.
401	UNAUTHORIZED	Missing, invalid, or expired API key / token.