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

1. Go to app.ekodb.io
2. Navigate to your deployment from the dashboard
3. 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 default, 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:

🦀 Rust

use ekodb_client::Client;

let client = Client::builder()
    .base_url("https://your-subdomain.production.aws.ekodb.io")
    .api_key("your-api-key-here")  // ← Your API key from the dashboard
    .build()?;

🐍 Python

from ekodb_client import Client

client = Client.new(
    "https://your-subdomain.production.aws.ekodb.io",
    "your-api-key-here"  # ← Your API key from the dashboard
)

📘 TypeScript

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

const client = new EkoDBClient({
  baseURL: "https://your-subdomain.production.aws.ekodb.io",
  apiKey: "your-api-key-here"  // ← Your API key from the dashboard
});

🔷 Go

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

client := ekodb.NewClient(
    "https://your-subdomain.production.aws.ekodb.io",
    "your-api-key-here",  // ← Your API key from the dashboard
)

Creating API Keys with Limited Permissions

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

Register API Key

Register a new API key for authentication:

HTTP

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}"
}

JavaScript

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;

🐍 Python

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']

Generate JWT Token

Generate a JWT token using your API key:

HTTP

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

{
  "api_key": "{YOUR_API_KEY}"
}

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

JavaScript

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;

🐍 Python

import requests

response = requests.post(
    'https://{EKODB_API_URL}/api/auth/token',
    headers={'Content-Type': 'application/json'},
    json={'api_key': '{YOUR_API_KEY}'}
)

token = response.json()['token']

Use JWT Token

Use the JWT token in the Authorization header:

HTTP

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

JavaScript

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

🐍 Python

import requests

response = requests.get(
    'https://{EKODB_API_URL}/api/collections',
    headers={'Authorization': 'Bearer {YOUR_JWT_TOKEN}'}
)

collections = response.json()

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.