Delete API Key

Delete an API key from a bucket. The key will immediately stop working.

Endpoint

DELETE /api/buckets/:bucketId/keys/:keyId

Authentication

Key Type	Allowed
Admin (dakkio_a_)	✅ Yes
Write (dakkio_w_)	❌ No
Read (dakkio_r_)	❌ No

Required: Admin key (dakkio_a_). Only Admin keys can delete API keys.

Immediate Effect

Once deleted, the API key will immediately stop working. Any devices or applications using this key will receive 401 Unauthorized errors.

Request

Headers

Header	Type	Required	Description
X-API-Key	string	✅ Yes	Your Admin API key

Path Parameters

Parameter	Type	Required	Description
bucketId	string	✅ Yes	The bucket ID (24-character hex string)
keyId	string	✅ Yes	The API key ID to delete (24-character hex string)

Example Request

curl -X DELETE "https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011/keys/507f1f77bcf86cd799439013" \
  -H "X-API-Key: dakkio_a_your_admin_key..."

Response

Success Response (200 OK)

{
  "message": "API key deleted successfully",
  "deletedKey": {
    "_id": "507f1f77bcf86cd799439013",
    "name": "Living Room Sensor",
    "type": "write"
  }
}

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Only Admin keys can delete API keys"
}

404 Not Found - Bucket

{
  "error": "Not Found",
  "message": "Bucket not found"
}

404 Not Found - Key

{
  "error": "Not Found",
  "message": "API key not found"
}

Code Examples

JavaScript/Node.js

const axios = require('axios');

async function deleteApiKey(bucketId, keyId) {
  const response = await axios.delete(
    `https://api.dakkio.io/api/buckets/${bucketId}/keys/${keyId}`,
    {
      headers: {
        'X-API-Key': process.env.DAKKIO_ADMIN_KEY
      }
    }
  );

  return response.data;
}

// Delete an API key
const result = await deleteApiKey(
  '507f1f77bcf86cd799439011',
  '507f1f77bcf86cd799439013'
);
console.log(`Deleted key: ${result.deletedKey.name}`);

Python

import requests
import os

def delete_api_key(bucket_id, key_id):
    response = requests.delete(
        f'https://api.dakkio.io/api/buckets/{bucket_id}/keys/{key_id}',
        headers={
            'X-API-Key': os.environ['DAKKIO_ADMIN_KEY']
        }
    )

    if response.status_code == 200:
        return response.json()
    else:
        print('Error:', response.json())
        return None

# Delete an API key
result = delete_api_key(
    '507f1f77bcf86cd799439011',
    '507f1f77bcf86cd799439013'
)
if result:
    print(f"Deleted key: {result['deletedKey']['name']}")

Use Cases

Revoking Compromised Keys

If a key is exposed or compromised:

// 1. Find the compromised key
const keys = await listApiKeys(bucketId);
const compromisedKey = keys.find(k => k.name === 'Exposed Device');

// 2. Delete it immediately
await deleteApiKey(bucketId, compromisedKey._id);

// 3. Create a new key
const newKey = await createApiKey(bucketId, 'Replacement Device', 'write');
console.log('New key:', newKey.key);

Rotating Keys Periodically

async function rotateKey(bucketId, keyName, keyType) {
  // Get current keys
  const keys = await listApiKeys(bucketId);
  const oldKey = keys.find(k => k.name === keyName);

  // Create new key first
  const newKey = await createApiKey(bucketId, keyName, keyType);
  console.log('New key created. Update your devices now.');
  console.log('New key:', newKey.key);

  // Wait for devices to update (or do this later)
  // await sleep(300000); // 5 minutes

  // Delete old key
  if (oldKey) {
    await deleteApiKey(bucketId, oldKey._id);
    console.log('Old key deleted');
  }

  return newKey;
}

Decommissioning a Device

async function decommissionDevice(bucketId, deviceName) {
  const keys = await listApiKeys(bucketId);
  const deviceKey = keys.find(k => k.name === deviceName);

  if (deviceKey) {
    await deleteApiKey(bucketId, deviceKey._id);
    console.log(`Decommissioned device: ${deviceName}`);
  } else {
    console.log(`No key found for device: ${deviceName}`);
  }
}

// Remove access for a retired sensor
await decommissionDevice(bucketId, 'Old Kitchen Sensor');

Best Practices

1. Verify Before Deleting

Always confirm the key name before deletion:

const keys = await listApiKeys(bucketId);
const keyToDelete = keys.find(k => k._id === keyId);

console.log(`About to delete: ${keyToDelete.name} (${keyToDelete.type})`);
// Confirm with user before proceeding

2. Create Replacement Before Deleting

When rotating keys, create the new key first:

// ✅ Good - create first, then delete
const newKey = await createApiKey(bucketId, 'Sensor', 'write');
// Update device with new key
await deleteApiKey(bucketId, oldKeyId);

// ❌ Bad - delete first (device has no working key)
await deleteApiKey(bucketId, oldKeyId);
const newKey = await createApiKey(bucketId, 'Sensor', 'write');

3. Update Applications

After deleting a key, ensure all applications using it are updated with a new key or gracefully handle the authentication failure.

Related Endpoints

• List API Keys - List all API keys for a bucket
• Create API Key - Create a new API key