Skip to main content

Create API Key

Create a new Write or Read API key for a bucket.

Endpoint​

POST /api/buckets/:bucketId/keys

Authentication​

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

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

Save Your Key!

The full API key is only returned once when created. Store it securely immediately. If you lose it, you'll need to create a new key.

API Key Types​

TypePrefixPermissions
writedakkio_w_Ingest data, create data sources, manage alerts
readdakkio_r_Query data, view analytics
Which type should I create?
  • Write keys for IoT devices, sensors, or any application that sends data
  • Read keys for dashboards, analytics tools, or anyone who only needs to view data
  • Create separate keys for each device or application for better security

Request​

Headers​

HeaderTypeRequiredDescription
X-API-Keystring✅ YesYour Admin API key
Content-Typestring✅ YesMust be application/json

Path Parameters​

ParameterTypeRequiredDescription
bucketIdstring✅ YesThe bucket ID (24-character hex string)

Body Parameters​

ParameterTypeRequiredDescription
namestring✅ YesDescriptive name for the key
typestring✅ YesKey type: write or read

Example Request - Create Write Key​

curl -X POST "https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011/keys" \
  -H "X-API-Key: dakkio_a_your_admin_key..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Living Room Sensor",
    "type": "write"
  }'

Example Request - Create Read Key​

curl -X POST "https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011/keys" \
  -H "X-API-Key: dakkio_a_your_admin_key..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dashboard Reader",
    "type": "read"
  }'

Response​

Success Response (201 Created)​

{
  "message": "API key created successfully",
  "apiKey": {
    "_id": "507f1f77bcf86cd799439013",
    "name": "Living Room Sensor",
    "type": "write",
    "key": "dakkio_w_abc123def456ghi789jkl012mno345pqr678",
    "bucketId": "507f1f77bcf86cd799439011",
    "createdAt": "2024-01-15T10:05:00Z"
  }
}
Important!

The key field contains the full API key. Save it now! It will never be shown again.

Error Responses​

400 Bad Request - Invalid Type​

{
  "error": "Validation Error",
  "message": "Invalid key type. Must be 'write' or 'read'"
}

400 Bad Request - Missing Name​

{
  "error": "Validation Error",
  "message": "Key name is required"
}

401 Unauthorized​

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

403 Forbidden​

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

404 Not Found​

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

Code Examples​

JavaScript/Node.js​

const axios = require('axios');

async function createApiKey(bucketId, name, type) {
  const response = await axios.post(
    `https://api.dakkio.io/api/buckets/${bucketId}/keys`,
    { name, type },
    {
      headers: {
        'X-API-Key': process.env.DAKKIO_ADMIN_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data.apiKey;
}

// Create a Write key for a sensor
const writeKey = await createApiKey(
  '507f1f77bcf86cd799439011',
  'Living Room Sensor',
  'write'
);
console.log('Write Key (SAVE THIS!):', writeKey.key);

// Create a Read key for dashboard
const readKey = await createApiKey(
  '507f1f77bcf86cd799439011',
  'Dashboard Reader',
  'read'
);
console.log('Read Key (SAVE THIS!):', readKey.key);

Python​

import requests
import os

def create_api_key(bucket_id, name, key_type):
    response = requests.post(
        f'https://api.dakkio.io/api/buckets/{bucket_id}/keys',
        headers={
            'X-API-Key': os.environ['DAKKIO_ADMIN_KEY'],
            'Content-Type': 'application/json'
        },
        json={
            'name': name,
            'type': key_type
        }
    )

    if response.status_code == 201:
        return response.json()['apiKey']
    else:
        print('Error:', response.json())
        return None

# Create a Write key
write_key = create_api_key(
    '507f1f77bcf86cd799439011',
    'Living Room Sensor',
    'write'
)
if write_key:
    print(f"Write Key (SAVE THIS!): {write_key['key']}")

# Create a Read key
read_key = create_api_key(
    '507f1f77bcf86cd799439011',
    'Dashboard Reader',
    'read'
)
if read_key:
    print(f"Read Key (SAVE THIS!): {read_key['key']}")

Best Practices​

1. Use Descriptive Names​

Name keys to identify what they're used for:

// ✅ Good names
"Living Room Sensor"
"Kitchen Temperature Monitor"
"Grafana Dashboard"
"Mobile App Reader"

// ❌ Bad names
"key1"
"test"
"sensor"

2. Create Separate Keys Per Device​

If one device is compromised, you can revoke just that key:

// Create a key for each device
await createApiKey(bucketId, 'ESP32-001 Living Room', 'write');
await createApiKey(bucketId, 'ESP32-002 Kitchen', 'write');
await createApiKey(bucketId, 'ESP32-003 Garage', 'write');

3. Use Read Keys for Viewing​

Don't give write access to tools that only need to read:

// Dashboard only needs to read data
await createApiKey(bucketId, 'Grafana Dashboard', 'read');

// Mobile app only displays data
await createApiKey(bucketId, 'iOS App', 'read');

4. Store Keys Securely​

  • Use environment variables, never hardcode
  • Use secrets management (AWS Secrets Manager, HashiCorp Vault)
  • Never commit keys to version control
# .env file (don't commit!)
DAKKIO_WRITE_KEY=dakkio_w_abc123...
DAKKIO_READ_KEY=dakkio_r_xyz789...