Security
Security is a top priority for ekoDB. Your data is protected with enterprise-grade features designed for production workloads.
Encryption
Data at Rest
All data stored in ekoDB is encrypted using AES-256-GCM encryption:
- Record data - All field values are encrypted before storage
- Encrypted IDs - Record identifiers are encrypted to prevent enumeration attacks
- WAL (Write-Ahead Log) - Transaction logs are encrypted
- Backups - All backup files inherit encryption
Data in Transit
- TLS 1.3 - All connections use modern TLS encryption
- Certificate validation - Strict certificate verification
- Perfect Forward Secrecy - Key exchange protects past sessions
Encryption Keys
ekoDB automatically manages encryption keys:
Database Key Structure:
├── Master Key (derived from your deployment)
├── Collection Keys (per-collection encryption)
└── Record Keys (per-record for sensitive data)
The admin key generated at the time of deploying your database is automatically encrypted and rotated by app.ekodb.io to secure your account. All other API keys (that you generate) are your responsibility to rotate as needed. See Creating Scoped API Keys below for how to generate new keys and revoke old ones.
Authentication
API Keys
ekoDB uses API keys for authentication. Each key is associated with specific permissions.
Key Types:
| Type | Description | Use Case |
|---|---|---|
| Admin Key | Full access to all operations | Development, deployment management |
| Scoped Key | Limited to specific collections | Production applications |
| Read-Only Key | Read access only | Analytics, reporting |
Creating Scoped API Keys
API key management is performed via the REST API. Pass the existing admin key
in the registration request's api_key field; the examples also send an admin
token. See Authentication for the full
registration contract.
POST /api/auth/register
Authorization: Bearer {ADMIN_TOKEN}
Content-Type: application/json
{
"api_key": "{ADMIN_KEY}",
"label": "production-backend",
"description": "Backend service API key",
"is_admin": false,
"collection_permissions": {
"users": ["read", "write"],
"products": ["read"],
"orders": ["read", "write"]
}
}
Response:
{
"id": "0123456789abcdef0123456789abcdef",
"key": "eko_prod_abc123...",
"label": "production-backend"
}
Omitting key lets the server generate the secret. In version 0.80.0, a
caller-selected key must contain at least 32 characters and 8 distinct
characters, and cannot be shaped like an id (32 lowercase hexadecimal
characters). The server generates id separately; use it for permission
resources and revocation. See API key management
for the complete response and the new permission routes.
Example with curl:
curl -X POST https://{EKODB_API_URL}/api/auth/register \
-H "Authorization: Bearer {ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"api_key": "{ADMIN_KEY}",
"label": "production-backend",
"description": "Backend service API key",
"is_admin": false,
"collection_permissions": {
"users": ["read", "write"],
"products": ["read"],
"orders": ["read", "write"]
}
}'
Once you have an API key, use it to initialize any client library:
- 🦀 Rust
- 🐍 Python
- 📘 TypeScript
- 📦 JavaScript
- 🟣 Kotlin
- 🔷 Go
use ekodb_client::Client;
let client = Client::builder()
.base_url("https://mydb.production.google.ekodb.net")
.api_key("eko_prod_abc123...")
.build()?;
from ekodb_client import Client
client = Client.new(
'https://mydb.production.google.ekodb.net',
'eko_prod_abc123...'
)
import { EkoDBClient } from '@ekodb/ekodb-client';
const client = new EkoDBClient({
baseURL: 'https://mydb.production.google.ekodb.net',
apiKey: 'eko_prod_abc123...'
});
await client.init();
const { EkoDBClient } = require('@ekodb/ekodb-client');
const client = new EkoDBClient({
baseURL: 'https://mydb.production.google.ekodb.net',
apiKey: 'eko_prod_abc123...'
});
await client.init();
import io.ekodb.client.EkoDBClient
val client = EkoDBClient.builder()
.baseUrl("https://mydb.production.google.ekodb.net")
.apiKey("eko_prod_abc123...")
.build()
import "github.com/ekoDB/ekodb-client-go"
client := ekodb.NewClient(
"https://mydb.production.google.ekodb.net",
"eko_prod_abc123...",
)
JWT Tokens
API keys are exchanged for JWT tokens for API access:
- Token Generation - Client libraries automatically handle this
- Token Lifetime - Default 1 hour (configurable)
- Token Refresh - Automatic refresh before expiration
- Token Revocation - Delete the API key to revoke all associated tokens
Access Control
Collection-Level Permissions
Control access at the collection level:
| Permission | Description |
|---|---|
read | Query, find, and search records |
write | Insert, update, and delete records |
Field-Level Access Control
Restrict access to specific fields within a collection:
{
"collection_permissions": {
"users": {
"read": true,
"write": true,
"select_fields": ["id", "name", "email"],
"exclude_fields": ["password_hash", "ssn"],
"writable_fields": ["name", "email", "preferences"]
}
}
}
| Field | Description |
|---|---|
select_fields | Only return these fields (allowlist) |
exclude_fields | Never return these fields (blocklist) |
writable_fields | Only allow writes to these fields |
Use exclude_fields to ensure sensitive data like password hashes, SSNs, or internal flags are never exposed to API consumers.
Stored Functions
A stored function is called through a call grant and runs as an identity. Functions has the full rules; this section is the security summary. These checks are enforced in the default enforce mode. On an instance running in shadow mode, a refused call grant, step permission or run identity is recorded as access_would_deny and allowed to proceed; admin-only routes, request validation and a function step's write to a system collection are enforced in both modes.
- Call grants. A key that is not an admin calls a stored function only through a
function_permissionsgrant: a function label, a label prefix ending in one*, or*for every function.callis the only right. Only an admin sets grants, at registration or on/api/auth/keys/{key_id}/permissions/functions/{pattern}, and each change is audited asfunction_permissions_updated. A call no grant covers is refused with403and audited asaccess_denied. Admin keys are unrestricted. A grant is carried in the token, so a removed grant stays usable through a token already issued until that token expires. - Run identity. A function declares
run_as:caller(the default) applies the calling key's collection, field-limit, key-value and call grants to every step;authorapplies the grants of the key recorded as the function's author, read from the key store when the call runs, and the run stops with403when that key is revoked or has expired. A function that records no author does not run for any caller until an admin setsrun_as: calleror saves it again. - Steps that leave the server.
HttpRequest,SWRandEmailSendrun only as an admin identity.ChatandEmbedhave no grant of their own and send data to model providers for any key that may call the function. - Records that name an identity. A generic data route refuses a non-admin key's write to the records of stored functions, schedules and webhook receivers, and a function step cannot write them for any identity, an admin's included. An admin key's generic write is how a ripple peer replicates these records, so it is not refused. The typed routes are what record the author or creator a run takes its identity from.
- What a function returns is visible to every key granted the function, and nothing redacts it. Operator environment values (
{{env.NAME}}) are filled into steps whatever identity the function runs as. - Schedules and webhook receivers call their function as the key that created them, and the function then runs as its own
run_as. A revoked or expired key does not run.
Audit trail for function writes
A write a stored function makes adds one entry per write step to the audit collection, after the step succeeds (after the commit, for a transactional function). The entry names the identity the steps ran as (the caller, or the recorded author under run_as: author) with the subject its token named, the function and the step, and, when the key that called the function is another key, that key. A read, a refused step, a failed step, and every step of a transactional function that rolls back add none, and a plain function that fails part-way keeps the entries of the steps that had already succeeded.
| Step | Event |
|---|---|
Insert | record_inserted |
BatchInsert | batch_insert |
Update, UpdateById, FindOneAndUpdate, UpdateWithAction, Upsert, Increment, Push | record_updated |
Delete, DeleteById | record_deleted |
BatchDelete | batch_delete |
KvSet, IdempotencyClaim, RateLimit, LockAcquire, SWR | kv_set |
KvDelete, LockRelease | kv_deleted |
The entry is one per step, not per record, so a Delete that matches many records is one record_deleted entry that names the collection. Steps cannot write the audit collection: a step that names it, directly or through a parameter, is refused.
Enforcement mode
The platform can run these checks in shadow mode (ACCESS_MODEL_MODE=shadow), where a refused call grant, step permission or run identity is allowed to go ahead and is audited as access_would_deny; admin-only routes, request validation and writes to system collections stay enforced. It is read once when the server starts and is not part of /api/config; unset, or any other value, enforces.
Reading the Audit Log
Audit logging is on by default (audit_logging in /api/config). Entries are records in the collection audit_<database name>, kept for audit_retention_days (up to 90 days by default, fewer on an instance with little memory). Each entry carries event_type, actor, target, detail and timestamp, and, where they apply, key_id, subject and source_ip.
Read entries with an ordinary find on that collection, using a key with read access to it (an admin key has it), with the same filters, sorting and limits as any other read:
curl -X POST https://{EKODB_API_URL}/api/find/audit_{DATABASE_NAME} \
-H "Authorization: Bearer {ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"type": "Condition",
"content": { "field": "event_type", "operator": "Eq", "value": "access_denied" }
},
"sort": [{ "field": "timestamp", "ascending": false }],
"limit": 100
}'
The audit collection is written only by ekoDB: an insert, update or delete aimed at it is refused with 403 (The audit collection is system-managed and cannot be modified via API).
Network Security
Supported Protocols
ekoDB only supports secure connections:
| Protocol | Status | Description |
|---|---|---|
| HTTPS | ✅ Supported | REST API connections |
| WSS | ✅ Supported | WebSocket connections |
| HTTP | ❌ Blocked | Rejected at load balancer |
| WS | ❌ Blocked | Rejected at load balancer |
Rate Limiting
Protect your deployment from abuse. On the managed platform, both authenticated API requests (made with your API key) and public (unauthenticated) endpoints are rate-limited per plan. The platform sets these limits for each plan; they are not changed through /api/config:
| Plan | Authenticated (req/min) | Public endpoints (req/min) |
|---|---|---|
| Free | 200 | 400 |
| Developer | 500 | 1,000 |
| Startup | 1,000 | 2,000 |
| Business | 2,000 | 4,000 |
| Professional | 5,000 | 10,000 |
| Enterprise Basic | 10,000 | 20,000 |
| Enterprise Standard | 15,000 | 30,000 |
Public endpoints — /api/health, /api/auth/register, /api/auth/token, and /api/auth/{api_key}/admin_key — are limited by client IP. Self-hosted deployments set the public limit with the PUBLIC_RATE_LIMIT_PER_MINUTE environment variable (default 60); see System Administration.
Rate Limit Responses:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706456400
IP Allowlisting (Enterprise)
Restrict API access to specific IP addresses or CIDR ranges:
{
"allowed_ips": [
"203.0.113.0/24",
"198.51.100.42"
]
}
API Key Management
Listing Keys
View all API keys for your deployment:
GET /api/auth/keys
Authorization: Bearer {ADMIN_TOKEN}
Rotating Keys
Best practice: Rotate API keys periodically.
- Create new key with same permissions via the REST API
- Update applications to use new key
- Delete old key after confirming new key works
# Step 1: Create new key
curl -X POST https://{EKODB_API_URL}/api/auth/register \
-H "Authorization: Bearer {ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"api_key": "{ADMIN_KEY}",
"label": "production-backend-v2",
"description": "Rotated key - January 2026",
"is_admin": false,
"collection_permissions": {
"users": ["read", "write"],
"products": ["read"]
}
}'
# Step 2: Update your application configuration with new key
# Step 3: Delete old key
curl -X DELETE https://{EKODB_API_URL}/api/auth/keys/{old_key_id} \
-H "Authorization: Bearer {ADMIN_TOKEN}"
Deleting Keys
Immediately revoke access by deleting an API key:
DELETE /api/auth/keys/{key_id}
Authorization: Bearer {ADMIN_TOKEN}
Deleting an API key immediately invalidates all JWT tokens generated from that key. Ensure you've updated all applications using that key first.
System Collection Secrets
In version 0.80.0, reads through generic data endpoints redact inline secrets
in the functions_, agent_function_versions_, webhook_receivers_, and
agent_webhooks_ system collections. A redacted value is a placeholder such
as <redacted:/path/to/field>.
An administrator can request the raw values with include_secrets=true.
Treat that response as secret-bearing data. A write containing a redaction
placeholder returns 400; a redacted export cannot be written back unchanged.
When copying stored functions, webhook settings, or deployment configuration, either retrieve the required raw values with an admin token or replace each placeholder with the destination's secret before writing. Keep those values out of logs, source control, and example files. This applies to inline secrets in system records; a placeholder is not a usable credential.
Security Best Practices
1. Use Environment Variables
Never hardcode API keys in source code:
# .env file (never commit to git!)
EKODB_API_KEY=eko_prod_abc123...
EKODB_URL=https://mydb.production.google.ekodb.net
- 🦀 Rust
- 🐍 Python
- 📘 TypeScript
- 📦 JavaScript
- 🟣 Kotlin
- 🔷 Go
use std::env;
use ekodb_client::Client;
let client = Client::builder()
.base_url(&env::var("EKODB_URL").expect("EKODB_URL not set"))
.api_key(&env::var("EKODB_API_KEY").expect("EKODB_API_KEY not set"))
.build()?;
import os
from ekodb_client import Client
client = Client.new(
os.environ['EKODB_URL'],
os.environ['EKODB_API_KEY']
)
import { EkoDBClient } from '@ekodb/ekodb-client';
const client = new EkoDBClient({
baseURL: process.env.EKODB_URL!,
apiKey: process.env.EKODB_API_KEY!
});
await client.init();
const { EkoDBClient } = require('@ekodb/ekodb-client');
const client = new EkoDBClient({
baseURL: process.env.EKODB_URL,
apiKey: process.env.EKODB_API_KEY
});
await client.init();
import io.ekodb.client.EkoDBClient
val client = EkoDBClient.builder()
.baseUrl(System.getenv("EKODB_URL"))
.apiKey(System.getenv("EKODB_API_KEY"))
.build()
import (
"os"
"github.com/ekoDB/ekodb-client-go"
)
client := ekodb.NewClient(
os.Getenv("EKODB_URL"),
os.Getenv("EKODB_API_KEY"),
)
2. Implement Least Privilege
Create separate API keys for different services:
| Service | Permissions |
|---|---|
| User Service | users: read, write |
| Analytics | users: read, events: read |
| Admin Dashboard | Admin key (restricted access) |
3. Monitor API Usage
Review access patterns in your ekoDB dashboard:
- Failed authentication attempts
- Unusual query patterns
- High-volume operations
4. Secure Your Infrastructure
- Use private networks when possible
- Enable firewall rules
- Implement audit logging
5. Handle Errors Securely
Never expose internal error details to clients:
- 🦀 Rust
- 🐍 Python
- 📘 TypeScript
- 📦 JavaScript
- 🟣 Kotlin
- 🔷 Go
match client.find("users", query, None).await {
Ok(result) => result,
Err(e) => {
// Log full error internally
eprintln!("Database error: {:?}", e);
// Return generic message to client
return Err(AppError::new("An error occurred. Please try again."));
}
}
try:
result = await client.find('users', query)
except Exception as e:
# Log full error internally
logger.error(f"Database error: {e}")
# Return generic message to client
raise HTTPException(status_code=500, detail="An error occurred. Please try again.")
try {
const result = await client.find('users', query);
} catch (error) {
// Log full error internally
console.error('Database error:', error);
// Return generic message to client
throw new Error('An error occurred. Please try again.');
}
try {
const result = await client.find('users', query);
} catch (error) {
// Log full error internally
console.error('Database error:', error);
// Return generic message to client
throw new Error('An error occurred. Please try again.');
}
try {
val result = client.find("users", query)
} catch (e: Exception) {
// Log full error internally
logger.error("Database error", e)
// Return generic message to client
throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "An error occurred. Please try again.")
}
result, err := client.Find("users", query)
if err != nil {
// Log full error internally
log.Printf("Database error: %v", err)
// Return generic message to client
http.Error(w, "An error occurred. Please try again.", http.StatusInternalServerError)
return
}
Compliance
ekoDB is designed with compliance in mind:
| Standard | Status |
|---|---|
| GDPR | ✅ Data encryption, deletion support |
| SOC 2 | 🔄 In progress |
| HIPAA | 📋 Available on Enterprise plan |
Data Deletion
Support GDPR "right to be forgotten":
- 🦀 Rust
- 🐍 Python
- 📘 TypeScript
- 📦 JavaScript
- 🟣 Kotlin
- 🔷 Go
use ekodb_client::QueryBuilder;
// Hard delete user data
client.delete("users", &user_id, None).await?;
// Delete related records by first finding their IDs, then batch-deleting
let query = QueryBuilder::new().eq("user_id", &user_id).build();
let events = client.find("user_events", query, None).await?;
let ids: Vec<String> = events
.iter()
.filter_map(|r| r.get_string("id"))
.collect();
client.batch_delete("user_events", ids, None).await?;
from ekodb_client import QueryBuilder
# Hard delete user data
await client.delete('users', user_id)
# Delete related records by first finding IDs, then batch-deleting
query = QueryBuilder().eq('user_id', user_id).build()
events = await client.find('user_events', query)
ids = [r['id'] for r in events]
await client.batch_delete('user_events', ids)
import { QueryBuilder } from '@ekodb/ekodb-client';
// Hard delete user data
await client.delete('users', userId);
// Delete related records by first finding IDs, then batch-deleting
const query = new QueryBuilder().eq('user_id', userId).build();
const events = await client.find('user_events', query);
const ids = events.map((r: Record<string, unknown>) => r.id as string);
await client.batchDelete('user_events', ids);
// Hard delete user data
await client.delete('users', userId);
// Delete related data with filter
await client.batchDelete('user_events', {
filter: {
type: 'Condition',
content: { field: 'user_id', operator: 'Eq', value: userId }
}
});
// Hard delete user data
client.delete("users", userId)
// Delete related data with filter
client.batchDelete("user_events", mapOf(
"filter" to mapOf(
"type" to "Condition",
"content" to mapOf(
"field" to "user_id",
"operator" to "Eq",
"value" to userId
)
)
))
// Hard delete user data
if err := client.Delete("users", userID); err != nil {
log.Fatal(err)
}
// Delete related records by first finding IDs, then batch-deleting
query := ekodb.NewQueryBuilder().Eq("user_id", userID).Build()
events, err := client.Find("user_events", query)
if err != nil {
log.Fatal(err)
}
ids := make([]string, 0, len(events))
for _, r := range events {
if id, ok := r["id"].(string); ok {
ids = append(ids, id)
}
}
if _, err := client.BatchDelete("user_events", ids); err != nil {
log.Fatal(err)
}
Vulnerability Reporting
Found a security issue? We take security seriously.
Report vulnerabilities to: security@ekodb.io
Response times:
- Critical: 24 hours
- High: 48 hours
- Medium: 1 week
- Low: 2 weeks
We follow responsible disclosure practices and will acknowledge your contribution.