Docs › Getting Started › Authentication

Authentication

Secure access to the Aevum Zenth API using API keys, OAuth 2.0, and ZenthID federation.

8 min read Security Critical

Last updated: Dec 14, 2025 Edit on GitHub →

⚠️

Production Warning

Never expose your secret API keys in client-side code or public repositories. Use environment variables and server-side proxying for all sensitive operations.

Overview

The Aevum Zenth platform supports multiple authentication methods depending on your use case. All API requests must be authenticated and sent over HTTPS.

API Keys — Server-to-server integrations and backend services.
ZenthID (OAuth 2.0) — User-facing applications requiring delegated access.
JWT Service Tokens — Short-lived tokens for microservice communication.

API Key Authentication

API keys are the simplest way to authenticate your backend services. Generate keys from the Zenth Console under Settings → API Keys.

ℹ️

Key Prefixes

Keys are prefixed to indicate their environment: az_live_ for production, az_test_ for sandbox. Using a live key in the test environment will result in a 403 error.

Making Requests

Include your API key in the Authorization header using the Bearer scheme:

HTTP

GET /v3/divisions HTTP/1.1
Host: api.aevumzenth.com
Authorization: Bearer az_live_sk_9f8e7d6c5b4a3210...
Content-Type: application/json

Key Rotation

For enhanced security, we recommend rotating your API keys every 90 days. You can generate multiple keys and deactivate old ones without downtime.

cURL

# Rotate API key via management endpoint
curl -X POST https://api.aevumzenth.com/v3/auth/rotate-key \
  -H "Authorization: Bearer az_live_sk_current_key" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2026-03-14T00:00:00Z",
    "label": "Production Backend v2"
  }'

ZenthID OAuth 2.0

For applications requiring user consent or accessing resources on behalf of an end-user, use ZenthID with the OAuth 2.0 Authorization Code Flow with PKCE.

Authorization Endpoint

URL

https://auth.aevumzenth.com/oauth/authorize

Required Parameters

Parameter	Type	Description
`client_id`	string	Your ZenthID application client ID.
`redirect_uri`	URI	The registered redirect URI for your application.
`response_type`	string	Must be `code`.
`scope`	string	Space-separated list of requested scopes.
`code_challenge`	string	PKCE code challenge (S256).
`code_challenge_method`	string	Must be `S256`.

Available Scopes

Scope	Access Level	Description
`openid` REQUIRED	Identity	Access to user identity information.
`read:energy`	Read	Read access to Energy Division data.
`write:energy`	Write	Modify energy grid configurations and reports.
`read:finance`	Read	Access financial instruments and balances.
`manage:workspace`	Admin	Manage workspace settings and members.

JavaScript

import { ZenthID } from '@aevumzenth/sdk'};

const zenth = new ZenthID({
  clientId: process.env.ZENTH_CLIENT_ID,
  redirectUri: 'https://your-app.com/callback',
});

// Generate PKCE verifier and challenge
const { codeChallenge, codeVerifier } = zenth.generatePKCE();

// Store verifier securely
sessionStorage.setItem('code_verifier', codeVerifier);

// Redirect to authorization
const authUrl = zenth.buildAuthUrl({
  scope: 'openid read:energy manage:workspace',
  codeChallenge,
});

window.location.href = authUrl;

JWT Service Tokens

For internal microservices, Aevum Zenth supports JWT-based authentication. Tokens are issued by the Identity Core and have a maximum TTL of 1 hour.

🔒

Token Security

Service tokens grant broad access based on attached roles. Restrict token generation to secure backend services and validate signatures on every request.

Token Structure

JSON

{
  "sub": "svc_grid_monitor_prod",
  "iss": "auth.aevumzenth.com",
  "aud": "api.aevumzenth.com",
  "exp": 1736726400,
  "iat": 1736722800,
  "roles": ["energy:reader", "reports:writer"],
  "division": "aevum-energy",
  "jti": "9a8b7c6d-5e4f-3210-abcd-ef1234567890"
}

Authentication Errors

Handle authentication failures gracefully by checking the HTTP status code and error payload.

Code	Message	Description
`401`	Unauthorized	Missing or invalid credentials. Check your API key or token.
`403`	Forbidden	Valid credentials but insufficient permissions or environment mismatch.
`401`	TokenExpired	The JWT or access token has expired. Refresh the token.
`429`	RateLimited	Too many authentication requests. Exponential backoff recommended.

Python

import requests

response = requests.get(
    "https://api.aevumzenth.com/v3/divisions",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

if response.status_code == 401:
    logger.error("Authentication failed. Verify API key.")
elif response.status_code == 403:
    logger.warning("Insufficient permissions or wrong environment.")
else:
    data = response.json()

← Previous

Quick Start Guide

Rate Limits & Quotas