# Intrasistema Changelog auth.md

This document defines the agent registration, authentication discovery, and authorization profile for autonomous AI agents and automated clients interacting with the **Intrasistema Changelog API**.

---

## 1. Agent Audience & Overview

The Intrasistema Changelog API provides read access to platform release notes, product updates, and version changelogs across Intrasistema WMS, App, and Signage systems.

- **Public Read Access:** Reading releases via `GET /api/releases`, the web UI, or syndication feeds is **100% open, public, and unauthenticated**. No login, credentials, session cookie, or bearer token is required to inspect release notes.
- **Administrative Write Access:** Publishing new releases (`POST /api/releases`) and triggering background translation synchronization (`POST /api/sync-translations`) require OAuth 2.0 bearer token authorization with the `releases:write` scope.
- **Audience:** Autonomous AI agents, web crawlers, automated software scanners, developer tools, and continuous integration agents.
- **Resource Server:** `https://changelog.intrasistema.com`
- **Authorization Server:** `https://changelog.intrasistema.com` (proxied / federated via `https://login.intrasistema.com`)

---

## 2. OAuth 2.0 Protected Resource Metadata (PRM)

Per [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728), clients can discover resource configuration for protected write operations at:

`GET /.well-known/oauth-protected-resource`

```json
{
  "resource": "https://changelog.intrasistema.com",
  "authorization_servers": [
    "https://changelog.intrasistema.com"
  ],
  "scopes_supported": [
    "releases:write"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_documentation": "https://changelog.intrasistema.com/docs",
  "public_access": "All release notes, public feeds, and changelog read operations are open and unauthenticated."
}
```

---

## 3. Authorization Server Metadata

Per [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) and OpenID Connect Discovery 1.0, authorization server metadata is served at:

- https://changelog.intrasistema.com/.well-known/oauth-authorization-server
- https://changelog.intrasistema.com/.well-known/openid-configuration

### Key Endpoints:
- **Issuer:** https://changelog.intrasistema.com
- **Authorization Endpoint:** https://login.intrasistema.com/oauth/authorize
- **Token Endpoint:** https://login.intrasistema.com/oauth/token
- **JWKS URI:** https://changelog.intrasistema.com/.well-known/jwks.json
- **Registration URI:** https://login.intrasistema.com/oauth/register

---

## 4. Agent Authentication & Registration Methods (`agent_auth`)

Autonomous agents can register and obtain credentials through Identity Assertion (ID-JAG):

### 4.1. Identity Assertion (ID-JAG)
- **Identity Type:** `identity_assertion`
- **Assertion Type:** `urn:ietf:params:oauth:token-type:id-jag`
- **Credential Types Supported:** `jwt`
- **Registration URI:** https://login.intrasistema.com/oauth/register
- **Claim URI:** https://login.intrasistema.com/oauth/claim

---

## 5. Token Usage

### 5.1 Public Read Requests (No Token Needed)
Public release queries do not require any token, header, or session:

```http
GET /api/releases HTTP/1.1
Host: changelog.intrasistema.com
Accept: application/json
```

### 5.2 Protected Administrative Requests (Bearer Token Required)
Administrative operations such as release ingestion or manual translation synchronization must supply the bearer token in the standard HTTP `Authorization` request header:

```http
POST /api/releases HTTP/1.1
Host: changelog.intrasistema.com
Authorization: Bearer <access_token>
Content-Type: application/json
```