MemgraphAI

Authentication

Memgraph supports two authentication methods: API Key for SDKs and programmatic access, and JWT Bearer Token for the Studio dashboard and user sessions.

API Key Authentication

API keys are the primary method for SDK and server-to-server access. Keys are prefixed with mg_ and are scoped to a single tenant.

Getting an API key

An API key is automatically generated when you onboard:

bash
curl -X POST https://api.memgraph.ai/v1/auth/onboard \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "YourSecurePassword123!",
    "full_name": "Your Name",
    "cluster_name": "My Workspace",
    "sector": "Technology"
  }'

# Response:
# {
#   "tenant_id": "uuid-here",
#   "api_key": "mg_live_abc123...",
#   "user_id": "uuid-here"
# }

You can also create additional keys from the dashboard or via API:

bash
# Create a new API key (requires JWT auth)
curl -X POST https://api.memgraph.ai/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-key"}'

# List keys
curl https://api.memgraph.ai/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Revoke a key
curl -X DELETE https://api.memgraph.ai/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Using the API key

Pass the key in the X-API-KEY header:

bash
curl https://api.memgraph.ai/v1/stats \
  -H "X-API-KEY: mg_live_your_key_here"
python
from memgraph_sdk import MemgraphClient

client = MemgraphClient(
    api_key="mg_live_your_key_here",
    tenant_id="your-tenant-uuid",
)
# All SDK methods automatically include the X-API-KEY header

Security: API keys are hashed with SHA-256 before storage. The plaintext key is only returned once at creation time. If you lose it, generate a new one.

JWT Bearer Token

JWT tokens are used for the Studio dashboard and user-facing sessions. Tokens are signed with HS256 and expire after 7 days by default.

Getting a token

bash
curl -X POST https://api.memgraph.ai/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]&password=YourPassword123!"

# Response:
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIs...",
#   "token_type": "bearer"
# }

Using the token

bash
curl https://api.memgraph.ai/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Returns your user profile with tenant_id, email, role

Roles (RBAC)

Memgraph uses role-based access control with three levels:

RoleLevelPermissions
admin3Full access. Export/import, manage users, manage API keys, tenant settings.
editor2Read/write events, beliefs, episodes. Cannot export or manage tenant.
viewer1Read-only access to events, beliefs, episodes, and stats.

The user who creates a tenant via onboard is automatically assigned the admin role. Roles are enforced on protected endpoints (e.g., /v1/admin/export requires admin).

Auth Priority

When both API key and JWT token are provided, the resolution order is:

  1. JWT Bearer token — checked first (user session takes priority)
  2. X-API-KEY header — checked second (SDK / programmatic access)
  3. No auth — rejected with 401, except in development mode where anonymous access is allowed

Public Endpoints

These endpoints do not require authentication:

GET /health

Health check with DB connectivity

GET /metrics

Prometheus metrics

POST /v1/auth/onboard

Create account + tenant

POST /v1/auth/login

Get JWT token