Skip to main content

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)
Key Management

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:

TypeDescriptionUse Case
Admin KeyFull access to all operationsDevelopment, deployment management
Scoped KeyLimited to specific collectionsProduction applications
Read-Only KeyRead access onlyAnalytics, 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"]
}
}'
Client Library Usage

Once you have an API key, use it to initialize any client library:

use ekodb_client::Client;

let client = Client::builder()
.base_url("https://mydb.production.google.ekodb.net")
.api_key("eko_prod_abc123...")
.build()?;

JWT Tokens​

API keys are exchanged for JWT tokens for API access:

  1. Token Generation - Client libraries automatically handle this
  2. Token Lifetime - Default 1 hour (configurable)
  3. Token Refresh - Automatic refresh before expiration
  4. Token Revocation - Delete the API key to revoke all associated tokens

Access Control​

Collection-Level Permissions​

Control access at the collection level:

PermissionDescription
readQuery, find, and search records
writeInsert, 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"]
}
}
}
FieldDescription
select_fieldsOnly return these fields (allowlist)
exclude_fieldsNever return these fields (blocklist)
writable_fieldsOnly allow writes to these fields
Sensitive Data

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_permissions grant: a function label, a label prefix ending in one *, or * for every function. call is 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 as function_permissions_updated. A call no grant covers is refused with 403 and audited as access_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; author applies the grants of the key recorded as the function's author, read from the key store when the call runs, and the run stops with 403 when that key is revoked or has expired. A function that records no author does not run for any caller until an admin sets run_as: caller or saves it again.
  • Steps that leave the server. HttpRequest, SWR and EmailSend run only as an admin identity. Chat and Embed have 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.

StepEvent
Insertrecord_inserted
BatchInsertbatch_insert
Update, UpdateById, FindOneAndUpdate, UpdateWithAction, Upsert, Increment, Pushrecord_updated
Delete, DeleteByIdrecord_deleted
BatchDeletebatch_delete
KvSet, IdempotencyClaim, RateLimit, LockAcquire, SWRkv_set
KvDelete, LockReleasekv_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:

ProtocolStatusDescription
HTTPS✅ SupportedREST API connections
WSS✅ SupportedWebSocket connections
HTTP❌ BlockedRejected at load balancer
WS❌ BlockedRejected 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:

PlanAuthenticated (req/min)Public endpoints (req/min)
Free200400
Developer5001,000
Startup1,0002,000
Business2,0004,000
Professional5,00010,000
Enterprise Basic10,00020,000
Enterprise Standard15,00030,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.

  1. Create new key with same permissions via the REST API
  2. Update applications to use new key
  3. 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}
Key Deletion

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
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()?;

2. Implement Least Privilege​

Create separate API keys for different services:

ServicePermissions
User Serviceusers: read, write
Analyticsusers: read, events: read
Admin DashboardAdmin 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:

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."));
}
}

Compliance​

ekoDB is designed with compliance in mind:

StandardStatus
GDPR✅ Data encryption, deletion support
SOC 2🔄 In progress
HIPAA📋 Available on Enterprise plan

Data Deletion​

Support GDPR "right to be forgotten":

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?;

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.