API Authentication & Access

Learn how to authenticate your requests to the Aevum Encyclopedia API using API keys, OAuth 2.0, and service tokens. Secure, scalable, and designed for production workloads.

Overview

Aevum Encyclopedia requires authentication for all API endpoints except public read-only routes. We support three authentication methods depending on your use case:

API Keys – Best for server-to-server communication and backend services
OAuth 2.0 – Recommended for user-facing applications and third-party integrations
Service Tokens – Designed for automated pipelines, CI/CD, and batch processing

ℹ️ Note

All authentication credentials must be kept secret. Never expose API keys or tokens in client-side code, public repositories, or browser-accessible files.

API Keys

API keys provide straightforward authentication for backend services. Generate keys from your Aevum Dashboard under Settings → API Access.

HTTP Request

curl -X GET "https://api.aevum.com/v2/articles/quantum-computing" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Key Permissions

Each API key can be scoped to specific permissions. Available scopes include:

Scope	Description	Default
`articles:read`	Retrieve article metadata and full content	✓
`search:query`	Access semantic search and knowledge graph queries	✓
`articles:write`	Create, update, or draft new entries	✗
`admin:manage`	Moderation, versioning, and access control	✗

OAuth 2.0 Flow

For applications that act on behalf of users, implement the standard OAuth 2.0 Authorization Code flow with PKCE.

Step 1: Authorization Request

Redirect URI

https://auth.aevum.com/oauth/authorize?
  response_type=code&
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  scope=articles:read+search:query&
  state=random_state_string&
  code_challenge=YOUR_PKCE_CHALLENGE

⚠️ Security Warning

Always validate the state parameter on callback to prevent CSRF attacks. Token exchange endpoints require TLS 1.2+ and mutual authentication for production scopes.

Step 2: Token Exchange

Exchange the authorization code for access and refresh tokens:

Token Request

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
client_id=your_client_id&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=YOUR_PKCE_VERIFIER

Required Headers

Every authenticated request must include the following headers:

Authorization – Bearer <token>
X-Aevum-Version – API version (e.g., 2.4)
Accept – application/json
X-Request-ID – UUID for tracing (recommended)

Rate Limits & Quotas

Authentication credentials are also tied to usage quotas. Standard limits:

Plan	Requests/min	Queries/hour	Burst
Free	30	1,000	5
Pro	300	25,000	50
Enterprise	Unlimited	Unlimited	Custom

When limits are exceeded, the API returns 429 Too Many Requests with a Retry-After header. Implement exponential backoff in your client.

← Previous Quickstart Guide Next → Core Endpoints