OAuth 2.0 Reference | Aevum News API

#Overview

Aevum News uses OAuth 2.0 for secure delegated access to user accounts and API resources. The authentication server is hosted at https://auth.aevumnews.com.

🔐 Public Clients

Single-page apps and mobile clients must use authorization_code with PKCE (code_challenge_method=S256).

🏢 Confidential Clients

Server-side applications use client credentials securely. Client secret authentication is required for token exchange.

⏱️ Token Lifetimes

Access tokens expire in 1 hour. Refresh tokens expire in 30 days and support single-use rotation.

#Authentication Endpoints

Method	Path	Description
GET	/authorize	Initiates user consent flow
POST	/token	Exchanges authorization code or credentials for tokens
POST	/revoke	Invalidates active or refresh tokens (RFC 7009)
POST	/introspect	Validates and returns token metadata (RFC 7662)

#Supported Grant Types

Authorization Code + PKCE

Recommended for public clients. Requires generating a code_verifier and code_challenge.

Authorize Request

GET https://auth.aevumnews.com/authorize?response_type=code
&client_id=your_client_id
&redirect_uri=https://your-app.com/callback
&scope=news:read analytics:read
&state=random_csrf_token
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256

Token Exchange

POST https://auth.aevumnews.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_FROM_REDIRECT
&client_id=your_client_id
&redirect_uri=https://your-app.com/callback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Client Credentials

For server-to-server API access without user context.

Client Credentials Request

POST https://auth.aevumnews.com/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=analytics:read

#Available Scopes

Scope	Description	Access Level
`news:read`	Read articles, headlines, and metadata	Public / User
`analytics:read`	Access engagement metrics and reader stats	Admin / Partner
`subscription:manage`	Create, update, or cancel user subscriptions	User
`user:profile`	Read/update account details and preferences	User
`admin:users`	Full user management and moderation	Admin Only

#Implementation Example

Using Fetch API with token handling:

JavaScript / Fetch

const response = await fetch('https://api.aevumnews.com/v1/articles', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

if (response.status === 401) {
  // Refresh token or redirect to /authorize
  await refreshAccessToken();
}

const data = await response.json();
console.log(data.articles);

Token Response Format

JSON Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "scope": "news:read analytics:read",
  "issued_at": 1718902345
}

#Error Responses

All error responses follow RFC 6749 Section 5.2:

Code	Description	HTTP Status
`invalid_request`	Missing or malformed parameter	400
`invalid_client`	Client authentication failed	401
`invalid_grant`	Expired/revoked code or token	400
`unauthorized_client`	Client not authorized for requested flow	403
`access_denied`	User declined consent	403
`invalid_scope`	Requested scope is unknown or invalid	400

#Security Requirements

TLS 1.2+ is mandatory for all authentication and API requests. HTTP is rejected.
PKCE is enforced for all public clients to prevent authorization code interception.
Token Binding: Refresh tokens are bound to client IP ranges and device fingerprints where applicable.
Rate Limiting: Token endpoint: 30 requests/minute per client. Exceeding limits returns 429 Too Many Requests.
Revocation: Users can revoke access at any time via account settings. Tokens become immediately invalid.

Revocation Request

POST https://auth.aevumnews.com/revoke
Content-Type: application/x-www-form-urlencoded

token=TOKEN_TO_REVOKE
&token_type_hint=access_token // or refresh_token