HeliosDB Authentication Guide

HeliosDB Authentication Guide

Secure Access with Bearer Token Authentication

HeliosDB uses Bearer token authentication for simple, secure API access. One token authenticates all protocols - REST API, PostgreSQL, MySQL, MongoDB, and Redis.

---

Overview

┌─────────────────────────────────────────────────────────────────┐
│                    HeliosDB Authentication                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────┐        ┌─────────────┐        ┌───────────┐  │
│   │   Sign Up   │───────▶│   Get Token │───────▶│  Use API  │  │
│   │   /signup   │        │   /login    │        │  Bearer   │  │
│   └─────────────┘        └─────────────┘        └───────────┘  │
│                                                                 │
│   Token Format: hdb_live_xxxxxxxxxxxxxxxxxxxxxxxxxx            │
│   Token Lifetime: 7 days (configurable)                        │
│   Refresh: Automatic or manual                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Getting Your Token

Option 1: CLI (Recommended)

# Install HeliosDB CLI
curl -fsSL https://get.heliosdb.io | sh

# Sign up and get token
helios auth signup
helios auth login
helios auth token

# Output: hdb_live_xxxxxxxxxxxxxxxxxxxx

Option 2: REST API

# Sign up
curl -X POST https://api.heliosdb.io/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password"
  }'

# Login and get token
curl -X POST https://api.heliosdb.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password"
  }'

Response:

{
  "token": "hdb_live_xxxxxxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "expires_at": "2025-12-23T00:00:00Z"
}

Option 3: Web Console

1. Visit console.heliosdb.io
2. Sign up or log in
3. Navigate to Settings → API Tokens
4. Click “Create Token”
5. Copy the token (shown only once)

---

Using Your Token

REST API

# Add to Authorization header
curl -X GET https://api.heliosdb.io/v1/databases \
  -H "Authorization: Bearer hdb_live_xxxxxxxxxxxxxxxxxxxx"

# Or use environment variable
export HELIOS_TOKEN="hdb_live_xxxxxxxxxxxxxxxxxxxx"

curl -X POST https://my-db.heliosdb.io/api/v1/sql \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT 1"}'

PostgreSQL

# Connection string
psql "postgresql://default:hdb_live_xxxxxxxxxxxxxxxxxxxx@my-db.heliosdb.io:5432/main"

# Or with environment variable
export PGPASSWORD="hdb_live_xxxxxxxxxxxxxxxxxxxx"
psql -h my-db.heliosdb.io -U default -d main

# Python
import psycopg2

conn = psycopg2.connect(
    host="my-db.heliosdb.io",
    port=5432,
    database="main",
    user="default",
    password=os.environ["HELIOS_TOKEN"]
)

MySQL

# Connection
mysql -h my-db.heliosdb.io -P 3306 -u default -p'hdb_live_xxxx' main

Node.js

const mysql = require('mysql2/promise');

const connection = await mysql.createConnection({
  host: 'my-db.heliosdb.io',
  port: 3306,
  user: 'default',
  password: process.env.HELIOS_TOKEN,
  database: 'main'
});

MongoDB

# Connection string
mongosh "mongodb://default:hdb_live_xxxx@my-db.heliosdb.io:27017/main"

# Python
from pymongo import MongoClient

client = MongoClient(
    f"mongodb://default:{os.environ['HELIOS_TOKEN']}@my-db.heliosdb.io:27017/main"
)

Redis

# Connection
redis-cli -h my-db.heliosdb.io -p 6379 -a 'hdb_live_xxxxxxxxxxxxxxxxxxxx'

# Python
import redis

r = redis.Redis(
    host='my-db.heliosdb.io',
    port=6379,
    password=os.environ['HELIOS_TOKEN']
)

---

Token Types

Live Tokens

Format: hdb_live_xxxxxxxxxxxxxxxxxxxxxxxxxx
Purpose: Production access
Permissions: Full access to account resources
Lifetime: 7 days (default), configurable

Test Tokens

Format: hdb_test_xxxxxxxxxxxxxxxxxxxxxxxxxx
Purpose: Development and testing
Permissions: Limited to test databases only
Lifetime: 24 hours

Service Tokens

Format: hdb_svc_xxxxxxxxxxxxxxxxxxxxxxxxxx
Purpose: CI/CD, automation, service accounts
Permissions: Scoped to specific operations
Lifetime: 90 days (no user session required)

Create service tokens via API:

curl -X POST https://api.heliosdb.io/v1/auth/tokens \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-cd-pipeline",
    "type": "service",
    "scopes": ["database:read", "database:write", "branch:create"],
    "expires_in_days": 90
  }'

---

Token Management

List Tokens

curl -X GET https://api.heliosdb.io/v1/auth/tokens \
  -H "Authorization: Bearer $HELIOS_TOKEN"

Response:

{
  "tokens": [
    {
      "id": "tok_xxxxxxxxxxxx",
      "name": "CLI Token",
      "type": "live",
      "last_used": "2025-12-16T10:30:00Z",
      "expires_at": "2025-12-23T00:00:00Z",
      "scopes": ["*"]
    },
    {
      "id": "tok_yyyyyyyyyyyy",
      "name": "ci-cd-pipeline",
      "type": "service",
      "last_used": "2025-12-15T08:00:00Z",
      "expires_at": "2026-03-15T00:00:00Z",
      "scopes": ["database:read", "database:write", "branch:create"]
    }
  ]
}

Refresh Token

# Refresh before expiration
curl -X POST https://api.heliosdb.io/v1/auth/refresh \
  -H "Authorization: Bearer $HELIOS_TOKEN"

Response:

{
  "token": "hdb_live_newtokenvalue",
  "expires_at": "2025-12-30T00:00:00Z"
}

Revoke Token

# Revoke specific token
curl -X DELETE https://api.heliosdb.io/v1/auth/tokens/tok_xxxxxxxxxxxx \
  -H "Authorization: Bearer $HELIOS_TOKEN"

# Revoke all tokens (logout everywhere)
curl -X POST https://api.heliosdb.io/v1/auth/logout-all \
  -H "Authorization: Bearer $HELIOS_TOKEN"

---

Scoped Permissions

Available Scopes

Scope	Description
*	Full access (default for live tokens)
database:read	Read from databases
database:write	Write to databases
database:create	Create new databases
database:delete	Delete databases
branch:read	Read branch information
branch:create	Create branches
branch:merge	Merge branches
branch:delete	Delete branches
schema:read	Read schema information
schema:write	Modify schema
vector:read	Vector search operations
vector:write	Insert vectors
metrics:read	Read usage metrics
billing:read	Read billing information
billing:write	Modify billing settings

Creating Scoped Tokens

# Read-only token for analytics
curl -X POST https://api.heliosdb.io/v1/auth/tokens \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "analytics-reader",
    "scopes": ["database:read", "metrics:read"],
    "expires_in_days": 30
  }'

# CI/CD token with branch access
curl -X POST https://api.heliosdb.io/v1/auth/tokens \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-actions",
    "scopes": ["database:read", "database:write", "branch:create", "branch:merge", "branch:delete"],
    "expires_in_days": 90
  }'

---

Security Best Practices

1. Environment Variables

# Store token in environment variable
export HELIOS_TOKEN="hdb_live_xxxxxxxxxxxxxxxxxxxx"

# Never hardcode tokens
# BAD:
conn = connect(password="hdb_live_xxxxxxxxxxxxxxxxxxxx")

# GOOD:
conn = connect(password=os.environ["HELIOS_TOKEN"])

2. Use Scoped Tokens

# Instead of using your main token everywhere,
# create scoped tokens for specific purposes

# For your web app (read + write to specific database)
helios token create --name "web-app" --scopes "database:read,database:write"

# For analytics dashboard (read only)
helios token create --name "analytics" --scopes "database:read,metrics:read"

# For CI/CD (branch operations)
helios token create --name "ci-cd" --scopes "branch:*"

3. Rotate Tokens Regularly

# Set up token rotation
# 1. Create new token
NEW_TOKEN=$(helios token create --name "app-v2" --output=json | jq -r '.token')

# 2. Update your application config
# 3. Verify new token works
# 4. Revoke old token
helios token revoke app-v1

4. Monitor Token Usage

# Check token activity
curl https://api.heliosdb.io/v1/auth/tokens \
  -H "Authorization: Bearer $HELIOS_TOKEN"

# Look for:
# - Unused tokens (revoke them)
# - Unexpected last_used times (potential breach)
# - Tokens near expiration (refresh them)

5. Use IP Allowlists (Enterprise)

# Restrict token to specific IPs
curl -X POST https://api.heliosdb.io/v1/auth/tokens \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-server",
    "allowed_ips": ["203.0.113.50", "203.0.113.51"],
    "scopes": ["database:read", "database:write"]
  }'

---

Framework Integration

Next.js

lib/helios.ts

import { Pool } from 'pg';

const pool = new Pool({
  host: process.env.HELIOS_HOST,
  database: 'main',
  user: 'default',
  password: process.env.HELIOS_TOKEN,
  ssl: true
});

export async function query(text: string, params?: any[]) {
  const client = await pool.connect();
  try {
    return await client.query(text, params);
  } finally {
    client.release();
  }
}

.env.local

HELIOS_HOST=my-db.heliosdb.io
HELIOS_TOKEN=hdb_live_xxxxxxxxxxxxxxxxxxxx

Django

settings.py

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': os.environ['HELIOS_HOST'],
        'NAME': 'main',
        'USER': 'default',
        'PASSWORD': os.environ['HELIOS_TOKEN'],
        'PORT': '5432',
        'OPTIONS': {
            'sslmode': 'require',
        },
    }
}

Ruby on Rails

config/database.yml

production:
  adapter: postgresql
  host: <%= ENV['HELIOS_HOST'] %>
  database: main
  username: default
  password: <%= ENV['HELIOS_TOKEN'] %>
  port: 5432
  sslmode: require

Express.js

db.js

const { Pool } = require('pg');

const pool = new Pool({
  host: process.env.HELIOS_HOST,
  database: 'main',
  user: 'default',
  password: process.env.HELIOS_TOKEN,
  ssl: { rejectUnauthorized: false }
});

module.exports = {
  query: (text, params) => pool.query(text, params)
};

---

Troubleshooting

Invalid Token Error

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Invalid or missing authentication token"
  }
}

Solutions:

1. Check token is not expired: helios auth status
2. Verify token format: Should start with hdb_live_, hdb_test_, or hdb_svc_
3. Ensure no whitespace in token
4. Refresh token: helios auth refresh

Token Expired Error

{
  "error": {
    "code": "AUTH_EXPIRED",
    "message": "Authentication token has expired"
  }
}

Solution:

helios auth refresh
# Or login again
helios auth login

Insufficient Permissions

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Token does not have required scope: database:write"
  }
}

Solution: Create a new token with required scopes or use a full-access token.

---

API Reference

Endpoint	Method	Description
/auth/signup	POST	Create new account
/auth/login	POST	Get authentication token
/auth/logout	POST	Invalidate current token
/auth/logout-all	POST	Invalidate all tokens
/auth/refresh	POST	Refresh expiring token
/auth/tokens	GET	List all tokens
/auth/tokens	POST	Create new token
/auth/tokens/:id	DELETE	Revoke specific token

---

Support

Need help with authentication?

• Documentation
• Discord Community
• Email Support

---

One Token. All Protocols. Complete Security.