API Key Management

All key management endpoints require JWT authentication via the Authorization: Bearer <token> header. See Authentication for how to obtain a JWT.

API keys themselves use the X-API-Key header and are used for all other agent endpoints.

Create Key

Create a new API key with the specified label and scopes.

POST /api/agent/auth/keys

Headers:

Authorization: Bearer <jwt_token>
Content-Type: application/json

Request Body:

Field	Type	Required	Description
label	string	Yes	A human-readable name for the key (max 64 characters)
scopes	string[]	Yes	Permissions: "read", "trade", or both

curl:

curl -X POST https://home.dobprotocol.com/api/agent/auth/keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "my-trading-bot",
    "scopes": ["read", "trade"]
  }'

Python:

import requests

resp = requests.post(
    "https://home.dobprotocol.com/api/agent/auth/keys",
    headers={"Authorization": f"Bearer {jwt_token}"},
    json={"label": "my-trading-bot", "scopes": ["read", "trade"]}
)
data = resp.json()
api_key = data["data"]["key"]
print(f"Save this key: {api_key}")

Response (201 Created):

{
  "success": true,
  "data": {
    "key_id": "ak_01HQ3K5M7N8P9Q0R1S2T3U4V5W",
    "key": "dob_ak_7f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a",
    "label": "my-trading-bot",
    "scopes": ["read", "trade"],
    "created_at": "2026-03-10T12:00:00Z"
  }
}

warning

The key field is only returned at creation time. Store it securely -- you cannot retrieve it later.

Limits: Each wallet can have up to 10 active API keys.

List Keys

Retrieve all API keys for the authenticated wallet. Keys are returned in masked form for security.

GET /api/agent/auth/keys

Headers:

Authorization: Bearer <jwt_token>

curl:

curl https://home.dobprotocol.com/api/agent/auth/keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Python:

resp = requests.get(
    "https://home.dobprotocol.com/api/agent/auth/keys",
    headers={"Authorization": f"Bearer {jwt_token}"}
)
keys = resp.json()["data"]
for key in keys:
    print(f"{key['label']}: {key['key_masked']} ({', '.join(key['scopes'])})")

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "key_id": "ak_01HQ3K5M7N8P9Q0R1S2T3U4V5W",
      "key_masked": "dob_ak_7f3a...9f0a",
      "label": "my-trading-bot",
      "scopes": ["read", "trade"],
      "created_at": "2026-03-10T12:00:00Z",
      "last_used_at": "2026-03-10T14:30:00Z"
    },
    {
      "key_id": "ak_02AB3C4D5E6F7G8H9I0J1K2L3M",
      "key_masked": "dob_ak_a1b2...f0e1",
      "label": "monitoring-dashboard",
      "scopes": ["read"],
      "created_at": "2026-03-09T08:00:00Z",
      "last_used_at": "2026-03-10T14:28:00Z"
    }
  ]
}

Revoke Key

Permanently revoke an API key. The key immediately stops working for all requests.

DELETE /api/agent/auth/keys/:keyId

Headers:

Authorization: Bearer <jwt_token>

Path Parameters:

Parameter	Type	Description
keyId	string	The key_id returned when the key was created

curl:

curl -X DELETE https://home.dobprotocol.com/api/agent/auth/keys/ak_01HQ3K5M7N8P9Q0R1S2T3U4V5W \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Python:

resp = requests.delete(
    "https://home.dobprotocol.com/api/agent/auth/keys/ak_01HQ3K5M7N8P9Q0R1S2T3U4V5W",
    headers={"Authorization": f"Bearer {jwt_token}"}
)
print(resp.json())

Response (200 OK):

{
  "success": true,
  "data": {
    "key_id": "ak_01HQ3K5M7N8P9Q0R1S2T3U4V5W",
    "revoked": true,
    "revoked_at": "2026-03-10T15:00:00Z"
  }
}

tip

If you suspect a key has been compromised, revoke it immediately and create a new one.

Rotate Key

Generate a new API key value while keeping the same key ID, label, and scopes. The old key is invalidated immediately, and the new key takes effect.

This is useful for scheduled key rotation without needing to update permissions or labels.

POST /api/agent/auth/keys/:keyId/rotate

Headers:

Authorization: Bearer <jwt_token>

Path Parameters:

Parameter	Type	Description
keyId	string	The key_id of the key to rotate

curl:

curl -X POST https://home.dobprotocol.com/api/agent/auth/keys/ak_01HQ3K5M7N8P9Q0R1S2T3U4V5W/rotate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Python:

resp = requests.post(
    "https://home.dobprotocol.com/api/agent/auth/keys/ak_01HQ3K5M7N8P9Q0R1S2T3U4V5W/rotate",
    headers={"Authorization": f"Bearer {jwt_token}"}
)
new_key = resp.json()["data"]["key"]
print(f"New key: {new_key}")

Response (200 OK):

{
  "success": true,
  "data": {
    "key_id": "ak_01HQ3K5M7N8P9Q0R1S2T3U4V5W",
    "key": "dob_ak_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
    "label": "my-trading-bot",
    "scopes": ["read", "trade"],
    "rotated_at": "2026-03-10T15:30:00Z"
  }
}

warning

The new key value is only returned once. Update your application immediately after rotation. The old key stops working as soon as rotation completes.

Error Responses

Scenario	HTTP Status	Error Code
Missing or invalid JWT	401	UNAUTHORIZED
Key not found	404	NOT_FOUND
Maximum keys reached (10)	400	VALIDATION_ERROR
Invalid scopes	400	VALIDATION_ERROR
Label too long	400	VALIDATION_ERROR

Example error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Maximum of 10 API keys per wallet. Revoke an existing key before creating a new one."
  }
}