Skip to main content

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 TypePrefixScopePermissions
Admindakkio_a_OrganizationFull access to all buckets and operations
Writedakkio_w_BucketData ingestion, data sources, alerts
Readdakkio_r_BucketData 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?​

TaskKey Type
Create/manage bucketsAdmin
Create/manage API keysAdmin
Ingest sensor dataWrite
Create data sourcesWrite
Set up alert rulesWrite
Query time-series dataRead
View analyticsRead
Batch data importWrite

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​