Authentication

All dakkio API endpoints use API Key authentication.

How It Works

1. Generate an API key from the dashboard or via the API
2. Store the key securely in your application
3. Include the key in the X-API-Key header with every request
4. Keys remain valid until deleted

Example:

curl -X GET https://api.dakkio.io/api/buckets \
  -H "X-API-Key: dakkio_a_xxxxxxxxxxxxxxxxxxxxx"

API Key Types

dakkio supports three types of API keys with different scopes and permissions:

Key Type	Prefix	Scope	Permissions
Admin	dakkio_a_	Organization	Full access to all buckets and operations
Write	dakkio_w_	Bucket	Data ingestion, data sources, alerts
Read	dakkio_r_	Bucket	Data queries, analytics

Admin Keys (Organization-Scoped)

• Access all buckets in the organization
• Can create and delete bucket-specific keys via API
• Can create, update, and delete buckets
• Best for: Management scripts, automation, cross-bucket operations

Example - List all buckets:

curl -X GET https://api.dakkio.io/api/buckets \
  -H "X-API-Key: dakkio_a_xxxxxxxxxxxxxxxxxxxxx"

Write Keys (Bucket-Scoped)

• Access only the assigned bucket
• Can ingest data and manage data sources
• Can create and manage alert rules
• Best for: IoT devices, data ingestion services

Example - Send sensor data:

curl -X POST https://api.dakkio.io/api/data \
  -H "X-API-Key: dakkio_w_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "507f1f77bcf86cd799439011",
    "dataSourceId": "507f1f77bcf86cd799439012",
    "values": { "temperature": 22.5 }
  }'

Read Keys (Bucket-Scoped)

• Read-only access to the assigned bucket
• Can query data and view analytics
• Cannot modify any data
• Best for: Dashboards, reporting tools, read-only integrations

Example - Query data:

curl -X POST https://api.dakkio.io/api/data/query \
  -H "X-API-Key: dakkio_r_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "507f1f77bcf86cd799439011",
    "filters": {
      "startTime": "2024-01-15T00:00:00Z",
      "endTime": "2024-01-15T23:59:59Z"
    }
  }'

Best Practice

Use bucket-specific keys (write/read) for IoT devices and per-service integrations. This follows the principle of least privilege - if a key is compromised, only one bucket is affected.

Programmatic Key Management

Use an admin key to create and manage bucket-specific keys via API:

# List all API keys for a bucket
curl -X GET https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011/keys \
  -H "X-API-Key: dakkio_a_xxxxxxxxxxxxxxxxxxxxx"

# Create a new write key for a bucket
curl -X POST https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011/keys \
  -H "X-API-Key: dakkio_a_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "write",
    "label": "Production IoT Devices"
  }'

# Delete a bucket key
curl -X DELETE https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011/keys/507f191e810c19729de860ea \
  -H "X-API-Key: dakkio_a_xxxxxxxxxxxxxxxxxxxxx"

Key Visibility

When you create a key, the plaintext value is returned only once. Store it securely immediately - it cannot be retrieved later.

Which Key Type to Use?

Task	Key Type
Create/manage buckets	Admin
Create/manage API keys	Admin
Ingest sensor data	Write
Create data sources	Write
Set up alert rules	Write
Query time-series data	Read
View analytics	Read
Batch data import	Write

Security Best Practices

✅ DO:

• Store keys in environment variables
• Use different keys for dev/staging/production
• Use bucket-scoped keys (write/read) when possible
• Rotate keys periodically
• Delete compromised keys immediately
• Use HTTPS for all requests

❌ DON'T:

• Hardcode keys in your source code
• Commit keys to version control
• Share keys publicly
• Use admin keys when bucket-scoped keys would work
• Use the same key across multiple services
• Include keys in URLs or query parameters

Next Steps

• Try the API Playground
• API Reference