Authentication

Secure access to the Aevum Encyclopedia API using API keys, OAuth 2.0, or session tokens. All endpoints require authentication unless explicitly marked as public.

Overview

Aevum supports three primary authentication methods:

API Keys – Best for server-to-server communication and backend services
OAuth 2.0 – Recommended for third-party applications and user-delegated access
Session Tokens – Used for authenticated client-side sessions (JWT-based)

ℹ️ Base URL

All authentication endpoints are hosted at https://api.aevum.enc/auth/v1/

API Keys

API keys provide direct access to your organization's workspace. Generate keys from the Developer Dashboard.

Request Format

Include your API key in the Authorization header as a Bearer token:

cURL

curl https://api.aevum.enc/v1/articles \
  -H "Authorization: Bearer aev_sk_live_8f3a9c2d7e1b504f" \
  -H "Content-Type: application/json"

⚠️ Security Notice

Never expose secret keys in client-side code. Use environment variables or a secure vault. Rotate keys immediately if compromised.

Key Scopes

Scope	Description	Rate Limit
`read:articles`	Access to encyclopedia entries & metadata	1,200 req/min
`write:articles`	Create, update, or delete entries (verified contributors only)	120 req/min
`admin:keys`	Manage API keys & workspace settings	50 req/min
`read:graph`	Access knowledge graph relationships & exports	800 req/min

OAuth 2.0

For applications requiring user authorization, Aevum implements the OAuth 2.0 Authorization Code flow with PKCE.

1. Authorization Request

Redirect users to the authorization endpoint:

HTTP

GET https://auth.aevum.enc/oauth/authorize?\
  client_id={YOUR_CLIENT_ID}\
  &redirect_uri={YOUR_REDIRECT_URI}\
  &response_type=code\
  &scope=read:articles+read:graph\
  &code_challenge={S256_CHALLENGE}\
  &code_challenge_method=S256

2. Exchange Code for Token

cURL

curl -X POST https://api.aevum.enc/auth/v1/token \
  -d "grant_type=authorization_code" \
  -d "code={AUTH_CODE}" \
  -d "client_id={CLIENT_ID}" \
  -d "client_secret={CLIENT_SECRET}" \
  -d "code_verifier={CODE_VERIFIER}" \
  -d "redirect_uri={YOUR_REDIRECT_URI}"

Response:

JSON

{
  "access_token": "aev_at_9x2k4m7p0q1r8s5t",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "aev_rt_3c6f9a2d5e8b1047",
  "scope": "read:articles read:graph"
}

Tokens & Sessions

Access tokens are short-lived (1 hour) and must be refreshed using the refresh token. Session management is handled automatically by client SDKs.

Refresh Token

cURL

curl -X POST https://api.aevum.enc/auth/v1/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "aev_rt_..."}'

✅ Best Practice

Store refresh tokens securely (HTTP-only cookies or encrypted storage). Implement token refresh logic before expiration to maintain seamless user experience.

Error Handling

Authentication errors return standard HTTP status codes with structured JSON responses:

Code	Message	Resolution
`401`	`invalid_credentials`	Verify API key or OAuth credentials
`401`	`token_expired`	Refresh the token or re-authenticate
`403`	`insufficient_scope`	Request additional scopes during authorization
`429`	`rate_limit_exceeded`	Implement exponential backoff

Error Response Structure:

JSON

{
  "error": "invalid_credentials",
  "error_description": "The provided API key is malformed or has been revoked.",
  "error_code": 401,
  "request_id": "req_8a3f9c2d7e1b504f"
}