Authentication

Getting Your API Key

After deploying your ekoDB instance, you'll need an API key to connect your application.

Step 1: Access Your Deployment

Go to app.ekodb.io
Navigate to your deployment from the dashboard
Click on the "Keys" tab

Direct link format: https://app.ekodb.io/deployments/{YOUR_DEPLOYMENT_ID}?active_tab=keys

Step 2: Use Your Admin API Key

By, ekoDB automatically generates an admin API key when you create a deployment. This key has full access to all collections and operations.

warning

Admin API keys should only be used for development and testing. For production applications, create API keys with limited permissions (see below).

Step 3: Copy Your API Key

Copy the API key from the dashboard and store it securely. You'll use this to initialize your client library.

Initialize Your Client

Once you have your API key, see the Client Libraries Installation Guide for complete code examples on how to configure your client in TypeScript, Rust, Python, Go, or Kotlin.

Client Libraries Handle Authentication

When using ekoDB client libraries (Rust, Python, TypeScript, Go, Kotlin), you don't need to manually manage JWT tokens. The client automatically handles token generation and renewal for you. Simply provide your API key when initializing the client.

Creating API Keys with Limited Permissions

For production applications, create API keys with specific collection permissions.

Register API Key

use ekodb_client::Client;

let client = Client::builder()
    .base_url("https://your-subdomain.production.google.ekodb.net")
    .api_key("ADMIN_KEY")
    .build()?;

let new_key = client.register_api_key(
    "LABEL",
    "DESCRIPTION",
    false, // is_admin
    Some(vec![("COLLECTION_NAME".to_string(), vec!["write".to_string(), "read".to_string()])])
).await?;

println!("New API Key: {}", new_key);

import requests

response = requests.post(
    'https://{EKODB_API_URL}/api/auth/register',
    headers={
        'Content-Type': 'application/json'
    },
    json={
        'api_key': '{ADMIN_KEY}',
        'label': '{LABEL}',
        'description': '{DESCRIPTION}',
        # Only required if you want to grant collection permissions to a non-admin API key
        'collection_permissions': {
            '{COLLECTION_NAME}': ['write', 'read']
        },
        'is_admin': True  # or False
    }
)

label = response.json()['label']
description = response.json()['description']
collection_permissions = response.json()['collection_permissions']
is_admin = response.json()['is_admin']
key = response.json()['key']

import { EkoDBClient } from "@ekodb/ekodb-client";

const client = new EkoDBClient({
  baseURL: "https://your-subdomain.production.google.ekodb.net",
  apiKey: "ADMIN_KEY"
});

const result = await client.registerApiKey({
  label: "LABEL",
  description: "DESCRIPTION",
  isAdmin: false,
  collectionPermissions: {
    "COLLECTION_NAME": ["write", "read"]
  }
});

const { label, description, collectionPermissions, isAdmin, key } = result;

const response = await fetch(
'https://{EKODB_API_URL}/api/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: '{ADMIN_KEY}',
    label: '{LABEL}',
    description: '{DESCRIPTION}',
    // Only required if you want to grant collection permissions to a non-admin API key
    collection_permissions: {
      '{COLLECTION_NAME}': ['write', 'read']
    },
    is_admin: true || false,
  })
});

const data = await response.json();
const label = data.label;
const description = data.description;
const collection_permissions = data.collection_permissions;
const is_admin = data.is_admin;
const key = data.key;

import io.ekodb.client.EkoDBClient

val client = EkoDBClient(
    baseUrl = "https://your-subdomain.production.google.ekodb.net",
    apiKey = "ADMIN_KEY"
)

val result = client.registerApiKey(
    label = "LABEL",
    description = "DESCRIPTION",
    isAdmin = false,
    collectionPermissions = mapOf(
        "COLLECTION_NAME" to listOf("write", "read")
    )
)

println("New API Key: ${result.key}")

import "github.com/ekoDB/ekodb-client-go"

client := ekodb.NewClient(
    "https://your-subdomain.production.google.ekodb.net",
    "ADMIN_KEY",
)

result, err := client.RegisterAPIKey(
    "LABEL",
    "DESCRIPTION",
    false, // isAdmin
    map[string][]string{
        "COLLECTION_NAME": {"write", "read"},
    },
)

if err != nil {
    panic(err)
}

fmt.Println("New API Key:", result.Key)

POST https://{EKODB_API_URL}/api/auth/register
Content-Type: application/json

{
  "api_key": "{ADMIN_KEY}",
  "label": "{LABEL}",
  "description": "{DESCRIPTION}",
  # Only required if you want to grant collection permissions to a non-admin API key
  "collection_permissions": {
    "{COLLECTION_NAME}": ["write", "read"]
  },
  "is_admin": true || false,
}

# Response
{
    "label": "{LABEL}",
    "description": "{DESCRIPTION}",
    "collection_permissions": {
        "{COLLECTION_NAME}": ["write", "read"]
    },
    "is_admin": true || false,
    "key": "{YOUR_NEW_API_KEY}"
}

Generate JWT Token

Generate a JWT token using your API key:

use ekodb_client::Client;

let client = Client::builder()
    .base_url("https://your-subdomain.production.google.ekodb.net")
    .api_key("YOUR_API_KEY")
    .build()?;

// Client automatically handles JWT token generation
// No manual token generation needed when using the client library

from ekodb_client import Client

client = Client.new(
    "https://your-subdomain.production.google.ekodb.net",
    "YOUR_API_KEY"
)

# Client automatically handles JWT token generation
# No manual token generation needed when using the client library

import { EkoDBClient } from "@ekodb/ekodb-client";

const client = new EkoDBClient({
  baseURL: "https://your-subdomain.production.google.ekodb.net",
  apiKey: "YOUR_API_KEY"
});

// Client automatically handles JWT token generation
// No manual token generation needed when using the client library

const response = await fetch(
'https://{EKODB_API_URL}/api/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ api_key: '{YOUR_API_KEY}' })
});

const data = await response.json();
const token = data.token;

import io.ekodb.client.EkoDBClient

val client = EkoDBClient(
    baseUrl = "https://your-subdomain.production.google.ekodb.net",
    apiKey = "YOUR_API_KEY"
)

// Client automatically handles JWT token generation
// No manual token generation needed when using the client library

import "github.com/ekoDB/ekodb-client-go"

client := ekodb.NewClient(
    "https://your-subdomain.production.google.ekodb.net",
    "YOUR_API_KEY",
)

// Client automatically handles JWT token generation
// No manual token generation needed when using the client library

POST https://{EKODB_API_URL}/api/auth/token
Content-Type: application/json

{
  "api_key": "{YOUR_API_KEY}"
}

# Response
{
  "token": "{YOUR_JWT_TOKEN}"
}

Client Libraries Handle Token Management

When using ekoDB client libraries (Rust, Python, TypeScript, Go, Kotlin), you don't need to manually generate JWT tokens. The client automatically handles token generation, caching, and renewal. Only use direct API calls for token generation if you're not using a client library.

Use JWT Token

Use the JWT token in the Authorization header:

use ekodb_client::Client;

let client = Client::builder()
    .base_url("https://your-subdomain.production.google.ekodb.net")
    .api_key("YOUR_API_KEY")
    .build()?;

// Client automatically handles authentication
let collections = client.list_collections().await?;

println!("Collections: {:?}", collections);

from ekodb_client import Client

client = Client.new(
    "https://your-subdomain.production.google.ekodb.net",
    "YOUR_API_KEY"
)

# Client automatically handles authentication
collections = client.list_collections()

print("Collections:", collections)

import { EkoDBClient } from "@ekodb/ekodb-client";

const client = new EkoDBClient({
  baseURL: "https://your-subdomain.production.google.ekodb.net",
  apiKey: "YOUR_API_KEY"
});

// Client automatically handles authentication
const collections = await client.listCollections();

console.log("Collections:", collections);

const response = await fetch(
'https://{EKODB_API_URL}/api/collections', {
  headers: { 'Authorization': 'Bearer {YOUR_JWT_TOKEN}' }
});

const collections = await response.json();
// collections now contains the list of available collections

import io.ekodb.client.EkoDBClient

val client = EkoDBClient(
    baseUrl = "https://your-subdomain.production.google.ekodb.net",
    apiKey = "YOUR_API_KEY"
)

// Client automatically handles authentication
val collections = client.listCollections()

println("Collections: $collections")

import "github.com/ekoDB/ekodb-client-go"

client := ekodb.NewClient(
    "https://your-subdomain.production.google.ekodb.net",
    "YOUR_API_KEY",
)

// Client automatically handles authentication
collections, err := client.ListCollections()
if err != nil {
    panic(err)
}

fmt.Println("Collections:", collections)

GET https://{EKODB_API_URL}/api/collections
Authorization: Bearer {YOUR_JWT_TOKEN}

Client Libraries Handle Authentication Automatically

When using ekoDB client libraries (Rust, Python, TypeScript, Go, Kotlin), you don't need to manually manage JWT tokens or set Authorization headers. Simply initialize the client with your API key, and all subsequent requests are automatically authenticated.

API Key Management

Manage API keys for your ekoDB instance.

List All API Keys

Get a list of all API keys (admin only).

GET https://{EKODB_API_URL}/api/auth/keys
Authorization: Bearer {ADMIN_TOKEN}

# Response
[
  {
    "key": "eko_prod_abc123...",
    "label": "Production API",
    "description": "Main production key",
    "is_admin": false,
    "collection_permissions": {
      "users": {
        "read": true,
        "write": true,
        "select_fields": null,
        "exclude_fields": null,
        "writable_fields": null
      },
      "posts": {
        "read": true,
        "write": false,
        "select_fields": null,
        "exclude_fields": null,
        "writable_fields": null
      }
    }
  },
  {
    "key": "eko_admin_def456...",
    "label": "Admin Key",
    "description": "Full admin access",
    "is_admin": true,
    "collection_permissions": {}
  }
]

Revoke API Key

Permanently revoke an API key (admin only).

DELETE https://{EKODB_API_URL}/api/auth/keys/{key_id}
Authorization: Bearer {ADMIN_TOKEN}

# Response
{
  "status": "success",
  "message": "Key revoked successfully"
}

Revocation is Permanent

Once revoked, an API key cannot be restored. Applications using the revoked key will immediately lose access.

Get User Permissions

Get the permissions for the currently authenticated user.

GET https://{EKODB_API_URL}/api/auth/permissions
Authorization: Bearer {YOUR_API_TOKEN}

# Response
{
  "key_id": "key_123",
  "label": "Production API",
  "is_admin": false,
  "collection_permissions": {
    "users": ["read", "write"],
    "posts": ["read"],
    "comments": ["read", "write", "delete"]
  }
}

Set Collection Permissions

Set collection permissions for an API key (admin only).

POST https://{EKODB_API_URL}/api/auth/permissions
Content-Type: application/json
Authorization: Bearer {ADMIN_TOKEN}

{
  "key_id": "key_123",
  "collection_permissions": {
    "users": ["read", "write"],
    "posts": ["read"],
    "analytics": []
  }
}

# Response
{
  "status": "updated",
  "key_id": "key_123",
  "collection_permissions": {
    "users": ["read", "write"],
    "posts": ["read"],
    "analytics": []
  }
}

Update Collection Permissions

Update existing collection permissions for an API key (admin only).

PUT https://{EKODB_API_URL}/api/auth/permissions
Content-Type: application/json
Authorization: Bearer {ADMIN_TOKEN}

{
  "key_id": "key_123",
  "collection_permissions": {
    "users": ["read", "write", "delete"],
    "posts": ["read", "write"]
  }
}

# Response
{
  "status": "updated",
  "key_id": "key_123",
  "collection_permissions": {
    "users": ["read", "write", "delete"],
    "posts": ["read", "write"]
  },
  "changes": [
    "Added 'delete' permission to 'users' collection",
    "Added 'write' permission to 'posts' collection"
  ]
}

Permission Levels

Collection Permissions

Permission	Description	Operations Allowed
`read`	View records in the collection	GET, query, search
`write`	Create and update records	POST (insert), PUT (update)
`delete`	Remove records	DELETE

Admin Permissions

Admin keys have full access to:

All collections (read, write, delete)
Collection creation and deletion
Schema management
Index management
API key management
System administration

Security Best Practice

Use admin keys only for initial setup and administrative tasks. For application access, create API keys with minimal required permissions.

Complete Example

Here's a complete authentication workflow:

#!/bin/bash

# 1. Create a new API key with specific permissions
response=$(curl -s -X POST https://{EKODB_API_URL}/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "{ADMIN_KEY}",
    "label": "Web App Key",
    "description": "API key for web application",
    "is_admin": false,
    "collection_permissions": {
      "users": ["read", "write"],
      "posts": ["read", "write"],
      "comments": ["read", "write", "delete"]
    }
  }')

new_api_key=$(echo $response | jq -r '.key')
echo "New API Key: $new_api_key"

# 2. Generate JWT token using the new key
token_response=$(curl -s -X POST https://{EKODB_API_URL}/api/auth/token \
  -H "Content-Type: application/json" \
  -d "{\"api_key\": \"$new_api_key\"}")

jwt_token=$(echo $token_response | jq -r '.token')
echo "JWT Token: $jwt_token"

# 3. Use the token to access allowed collections
curl -X GET https://{EKODB_API_URL}/api/find/users \
  -H "Authorization: Bearer $jwt_token"

# 4. Verify permissions
curl -X GET https://{EKODB_API_URL}/api/auth/permissions \
  -H "Authorization: Bearer $jwt_token"

# 5. Update permissions (requires admin key)
curl -X PUT https://{EKODB_API_URL}/api/auth/permissions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ADMIN_TOKEN}" \
  -d '{
    "key_id": "key_123",
    "collection_permissions": {
      "users": ["read"],
      "posts": ["read"]
    }
  }'

# 6. List all API keys (admin only)
curl -X GET https://{EKODB_API_URL}/api/auth/keys \
  -H "Authorization: Bearer {ADMIN_TOKEN}"

# 7. Revoke a key when no longer needed
curl -X DELETE https://{EKODB_API_URL}/api/auth/keys/key_123 \
  -H "Authorization: Bearer {ADMIN_TOKEN}"

Best Practices

API Key Security

Do:

✅ Store API keys securely (environment variables, secrets manager)
✅ Use different keys for development, staging, and production
✅ Create keys with minimal required permissions
✅ Rotate keys regularly
✅ Revoke keys immediately if compromised

Don't:

❌ Hardcode API keys in source code
❌ Commit keys to version control
❌ Share admin keys with applications
❌ Use the same key across multiple environments
❌ Expose keys in client-side code

Permission Strategy

Principle of Least Privilege:

# Good: Minimal permissions
{
  "users": ["read"],           # Read-only for users
  "analytics": []              # No access to analytics
}

# Avoid: Excessive permissions
{
  "users": ["read", "write", "delete"],  # More than needed
  "is_admin": true                       # Full access when not required
}

Token Lifecycle

JWT Token Expiration:

JWT tokens expire after a period (default: 1 hour). When using direct HTTP API, implement token refresh:

# Check if token is expired
if token_expired; then
  # Regenerate token
  new_token=$(curl -X POST .../api/auth/token \
    -d '{"api_key": "YOUR_KEY"}' | jq -r '.token')
fi

Client Libraries Handle This

When using ekoDB client libraries, token refresh is automatic. You don't need to manually check expiration.

Troubleshooting

Common Authentication Errors

401 Unauthorized:

{
  "error": "Invalid or expired token"
}

Solution: Regenerate JWT token using your API key.

403 Forbidden:

{
  "error": "No write permission for collection users"
}

Solution: Update API key permissions to include required access.

Invalid API Key:

{
  "error": "API key not found or revoked"
}

Solution: Verify the API key is correct and hasn't been revoked.

Basic Operations - Using authenticated requests
Collections & Schemas - Managing collections

Great! You can now use the JWT token to authenticate your requests to the ekoDB API.

Next, you can learn how to use the ekoDB API to manage your data!

If you have any issues, please email support@ekodb.io to create a ticket.

Getting Your API Key​

Step 1: Access Your Deployment​

Step 2: Use Your Admin API Key​

Step 3: Copy Your API Key​

Creating API Keys with Limited Permissions​

Register API Key​

Generate JWT Token​

Use JWT Token​

API Key Management​

List All API Keys​

Revoke API Key​

Get User Permissions​

Set Collection Permissions​

Update Collection Permissions​

Permission Levels​

Collection Permissions​

Admin Permissions​

Complete Example​

Best Practices​

API Key Security​

Permission Strategy​

Token Lifecycle​

Troubleshooting​

Common Authentication Errors​

Related Documentation​