Authentication

Introduction

Authentication is a process of verifying the identity of a user or application. ekoDB uses API keys for authentication. API keys are used to request for a JWT token, which is then used to authenticate requests to the ekoDB API.

By default, ekoDB App generates an admin API key for your convenience. This admin API key is generated when you first create an ekoDB instance. You can find it in the ekoDB App under the Keys tab within the database deployment view:

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

You can use this API key or generate a new API key by following the Register API Key section below.

Register API Key

HTTP
JavaScript
Python

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

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 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
JavaScript
Python

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

{
  "api_key": "{YOUR_API_KEY}"
}

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

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 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
JavaScript
Python

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

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 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.

Introduction​

Register API Key​

Generate JWT Token​

Use JWT Token​

Introduction

Register API Key

Generate JWT Token

Use JWT Token