Authentication

v2.4.1 · Stable

All Aevum Zenth API endpoints are secured using standardized authentication mechanisms. Choose the method that best fits your integration scope, environment, and security requirements.

Quick Start

Generate an API key from the Developer Console under Project Settings → API Keys.
Include the key in the Authorization header as a Bearer token.
Verify connectivity with the /v2/health endpoint.

cURL

curl https://api.aevumzenth.com/v2/health \
  -H "Authorization: Bearer az_live_sk_8f9c2a1b..." \
  -H "X-AZ-Client-ID: your_client_id"

Supported Methods

1. API Keys (Recommended for Server-Side)

Static keys scoped to specific projects and environments. Ideal for backend services, CI/CD pipelines, and internal tooling.

⚠️

Security Note: Never expose live API keys in client-side code, public repositories, or browser-accessible environments. Use environment variables or secret managers.

2. OAuth 2.0 / OIDC (For User Delegation)

Use the Authorization Code Flow with PKCE for applications requiring user-specific data access. Aevum Zenth supports standard OIDC discovery at https://auth.aevumzenth.com/.well-known/openid-configuration.

Parameter	Description	Required
`client_id`	Your registered OAuth client identifier	Yes
`redirect_uri`	Registered callback URL	Yes
`scope`	Space-separated permission scopes (e.g., `read:users write:analytics`)	Yes
`code_challenge`	S256 PKCE code challenge	Yes

3. JWT Bearer Tokens (Short-Lived)

For service-to-service communication or time-bound access, generate JWTs signed with RS256 or ES256. Tokens expire after 15 minutes by default and must be refreshed via the token endpoint.

Request Headers

Header	Description	Example
`Authorization`	Bearer token or API key	`Bearer az_live_sk_...`
`Content-Type`	Request body format	`application/json`
`X-AZ-Client-ID`	Environment/project identifier	`prod_us_east_1`
`Idempotency-Key`	Prevent duplicate operations	`uuid_v4_string`

Code Examples

JavaScript (Fetch)

JavaScript

const response = await fetch('https://api.aevumzenth.com/v2/resources', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.AZ_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

if (!response.ok) throw new Error(`Auth failed: ${response.status}`);
const data = await response.json();

Python (Requests)

Python

import requests

headers = {
    "Authorization": f"Bearer {os.getenv('AZ_API_KEY')}",
    "X-AZ-Client-ID": "prod_us_east_1"
}

response = requests.get(
    "https://api.aevumzenth.com/v2/resources",
    headers=headers
)
response.raise_for_status()
data = response.json()

Error Responses

Authentication failures return standard HTTP status codes with structured JSON payloads:

Status	Code	Description
401	`INVALID_CREDENTIALS`	Missing, malformed, or expired token/key
403	`INSUFFICIENT_SCOPES`	Token lacks required permissions
403	`IP_RESTRICTED`	Request origin not in allowlist
429	`RATE_LIMIT_EXCEEDED`	Too many auth attempts (10 req/min)

💡

Debug Tip: Always check the X-AZ-Request-ID header in responses. Include it when contacting support for faster troubleshooting.

Best Practices

Rotate API keys every 90 days using the console or /v2/security/rotate-key endpoint.
Apply least-privilege scopes to OAuth clients and service accounts.
Enable IP allowlisting for production workloads in the Developer Portal.
Use short-lived JWTs for ephemeral processes; cache tokens securely.
Monitor auth metrics via /v2/analytics/security for anomaly detection.

Need integration help? devsupport@aevumzenth.com or join our Developer Discord.