API Overview

Welcome to the Heimdall API documentation. This API provides a comprehensive set of endpoints for managing GPS tracking data, system settings, and real-time communication.

Base URL

Production: https://api.elcto.com
Development: http://localhost:3000

All API endpoints are available under the /v1 prefix.

API Version

Current version: v1

All API endpoints are prefixed with /v1 (except health check and root endpoints).

Available APIs

Heimdall provides three main API interfaces:

REST API

Traditional RESTful API with full CRUD operations, pagination, and HATEOAS links.

Endpoints: /v1/*
Authentication: Bearer token
Format: JSON
Documentation: Interactive Swagger UI

GraphQL API

Flexible query language for efficient data fetching and mutations.

Endpoint: /v1/gql (requires authentication)
GraphiQL IDE: /v1/graphiql (interactive interface, no auth)
Schema: /v1/schema (SDL format, no auth)
Authentication: Required Bearer token for /v1/gql
Features: Introspection, batching, type-safe queries

WebSocket API

Real-time bidirectional communication for live GPS updates and notifications.

Endpoint: ws://api.elcto.com/v1/ws
Protocol: WebSocket
Features: Channel subscriptions, heartbeat monitoring, automatic reconnection

Key Features

RESTful Design - Clean, predictable resource-based URLs
HATEOAS Links - Self-documenting API with hypermedia links
Authentication - Secure token-based authentication
Rate Limiting - Protection against abuse
Pagination - Efficient handling of large datasets
Real-time Updates - WebSocket support for live data
GraphQL - Flexible querying with exact data needs
CORS Support - Environment-aware cross-origin requests
Comprehensive Errors - Detailed error messages with codes

Quick Start

1. Get an API Token

Contact your administrator to obtain an API token.

2. Make Your First Request

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.elcto.com/v1/gps/current

3. Explore the API

Visit our Interactive Swagger UI to explore all available endpoints and try them out.

API Endpoints

Category	Endpoints	Description
Health	`GET /health`, `GET /v1/health`	System health check
Info	`GET /v1`	API version info
Auth	`POST /v1/auth/*`	Authentication & validation
GPS	`/v1/gps/*`	GPS data management
Settings	`/v1/settings/*`	System configuration
Stats	`/v1/stats/*`	Platform statistics
API Keys	`/v1/api-keys/*`	API key management
Roles	`/v1/roles/*`	Role management
Permissions	`/v1/permissions/*`	Permission management
Users	`/v1/users/*`	User management
Sessions	`/v1/users/me/sessions/*`	Active session management
2FA	`/v1/users/me/2fa/*`	Two-factor authentication
Activity Log	`/v1/users/me/audit/*`	User activity & audit events
Audit Reports	`/v1/admin/audit/reports/*`	Admin audit report management
User Bans	`/v1/admin/bans/*`	Admin user ban management
Data Export	`GET /v1/user/export`	GDPR data export
OAuth Clients	`/v1/oauth/clients/*`	OAuth app management
Platforms	`/v1/platforms/*`	Authentication platforms
WebSocket	`WS /v1/ws`	Real-time communication
GraphQL	`POST /v1/gql`, `GET /v1/graphiql`	GraphQL queries/mutations

Response Format

All REST API responses follow a consistent format with HATEOAS links:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "latitude": 51.5074,
    "longitude": -0.1278
  },
  "_links": {
    "self": "https://api.elcto.com/v1/gps/550e8400-e29b-41d4-a716-446655440000"
  }
}

Configuration

GeoIP Location Lookup

The API supports IP-to-location lookup for audit events using the MaxMind GeoLite2 City database. This enables showing geographic information (city, region, country) in activity logs.

Setup:

Register for a free license key at MaxMind GeoLite2
Download the database using the built-in updater:

# Using just command
just geoip-update

# Or directly
MAXMIND_LICENSE_KEY=your_key cargo run --bin geoip-update

TOML Configuration (config/default.toml):

[geoip]
# Path to the MaxMind GeoLite2 City database file (.mmdb)
database_path = "data/GeoLite2-City.mmdb"
# MaxMind license key for downloading/updating the database
license_key = ""
# MaxMind account ID (numeric) for Privacy Exclusions API
account_id = ""
# Enable automatic database updates on server startup
auto_update = false
# Update interval in days (default: 7, MaxMind updates weekly)
update_interval_days = 7
# Enable Privacy Exclusions API to respect user opt-outs
privacy_exclusions_enabled = false
# How often to refresh privacy exclusions (in hours)
privacy_exclusions_refresh_hours = 24
# Path to cache file for privacy exclusions
privacy_exclusions_cache_path = "data/geoip-privacy-exclusions.json"

Environment Variable Overrides:

Variable	Description
`GEOIP_DATABASE_PATH`	Path to the .mmdb database file
`MAXMIND_LICENSE_KEY`	License key for downloads
`MAXMIND_ACCOUNT_ID`	Account ID for Privacy Exclusions API
`GEOIP_AUTO_UPDATE`	Enable auto-update (`true`/`false`)
`GEOIP_UPDATE_INTERVAL_DAYS`	Days between updates
`GEOIP_PRIVACY_EXCLUSIONS_ENABLED`	Enable Privacy Exclusions API
`GEOIP_PRIVACY_EXCLUSIONS_REFRESH_HOURS`	Hours between exclusion refreshes
`GEOIP_PRIVACY_EXCLUSIONS_CACHE_PATH`	Path to exclusions cache file

Just Commands:

Command	Description
`just geoip-update`	Download/update GeoIP database
`just geoip-update-force`	Force re-download even if recent
`just geoip-status`	Check if database exists

Privacy Exclusions API:

The Privacy Exclusions API allows respecting users who have opted out of geolocation tracking via MaxMind's Privacy Exclusions. When enabled:

The service fetches excluded IPs/networks from MaxMind on startup
Exclusions are cached locally in a JSON file for persistence
Cache is refreshed at the configured interval (default: 24 hours)
Any lookup for an excluded IP returns no location data

If no GeoIP database is configured, audit events will still be logged but without location data.

Sentry Error Tracking

The API supports Sentry integration for error tracking and performance monitoring.

TOML Configuration (config/default.toml):

[sentry]
# Enable Sentry error tracking
enabled = true
# Sentry DSN (Data Source Name) - get from Sentry project settings
dsn = "https://your-key@sentry.io/your-project-id"
# Environment name (e.g., "production", "staging", "development")
environment = "production"
# Sample rate for performance tracing (0.0 to 1.0)
traces_sample_rate = 1.0
# Sample rate for error events (0.0 to 1.0)
sample_rate = 1.0
# Enable Sentry SDK debug mode
debug = false
# Attach stack traces to messages
attach_stacktrace = true
# Send default PII (personally identifiable information)
send_default_pii = false
# Maximum number of breadcrumbs to capture
max_breadcrumbs = 100

Environment Variable Overrides:

Variable	Description
`SENTRY_DSN`	Sentry DSN (auto-enables if set)
`SENTRY_ENVIRONMENT`	Environment name
`SENTRY_TRACES_SAMPLE_RATE`	Traces sample rate
`SENTRY_SAMPLE_RATE`	Error sample rate
`SENTRY_DEBUG`	Enable debug mode

Setting SENTRY_DSN automatically enables Sentry even if enabled = false in the config.

What Gets Captured:

Database errors (5xx)
Redis errors (5xx)
Internal server errors (5xx)
Performance traces for all requests (based on traces_sample_rate)
Breadcrumbs for INFO, WARN, and ERROR log levels

What Is NOT Captured:

Client errors (4xx) - these are logged locally but not sent to Sentry
DEBUG and TRACE level logs

Base URL​

API Version​

Available APIs​

REST API​

GraphQL API​

WebSocket API​

Key Features​

Quick Start​

1. Get an API Token​

2. Make Your First Request​

3. Explore the API​

API Endpoints​

Response Format​

Configuration​

GeoIP Location Lookup​

Sentry Error Tracking​

Next Steps​