# auth.md - manypost Agent Registration & Authentication

## Overview

Welcome to the **manypost** Agent Authentication specification (`auth.md`). This document describes how autonomous AI agents, Model Context Protocol (MCP) clients, and programmatic tools can discover, register, and authenticate securely with the manypost API ecosystem.

manypost is the premier multichannel social media scheduling and analytics platform for creators, agencies, and autonomous AI agents (`https://manypost.com.br`).

---

## 1. Discovery Metadata & Protected Resources

Before initiating authentication or registration, agents MUST consult our standardized discovery endpoints:

- **OAuth 2.0 Authorization Server Metadata (RFC 8414)**:
  `https://manypost.com.br/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery (OIDC)**:
  `https://manypost.com.br/.well-known/openid-configuration`
- **OAuth Protected Resource Metadata (RFC 9728)**:
  `https://manypost.com.br/.well-known/oauth-protected-resource`
- **API Catalog & OpenAPI Spec (RFC 9727)**:
  `https://manypost.com.br/.well-known/api-catalog` (`https://manypost.com.br/.well-known/openapi.json`)
- **Agent Skills Discovery Index**:
  `https://manypost.com.br/.well-known/agent-skills/index.json`
- **MCP Server Card (SEP-1649)**:
  `https://manypost.com.br/.well-known/mcp/server-card.json`

---

## 2. Official API Authentication & Registration Flows

The manypost backend (`https://api.manypost.com.br`) supports both **RESTful Account Authentication** and **Autonomous Agent Assertions**:

### A. RESTful Account Registration & Login (`/v1/auth/*`)
- **Register New User & Organization**:
  `POST https://api.manypost.com.br/v1/auth/register`
  Body: `{ "email": "agent@example.com", "password": "...", "name": "Agent Bot", "orgName": "AI Agency" }`
  Returns: `accessToken`, `refreshToken`, `user`, and `org`.
- **User Login**:
  `POST https://api.manypost.com.br/v1/auth/login`
  Body: `{ "email": "agent@example.com", "password": "..." }`
- **API Key Creation**:
  `POST https://api.manypost.com.br/v1/api-keys`
  Body: `{ "name": "MCP Production Key", "scopes": ["posts:write", "channels:read", "media:write"] }`

### B. Autonomous Agent Grant Flows (`oauth_token`)
- **Flow 1: ID-JAG (Identity Assertion Grant - Preferred for Autonomous Agents)**
  - **Identity Type**: `identity_assertion`
  - **Assertion Type**: `urn:ietf:params:oauth:token-type:id-jag`
  - **Registration Endpoint**: `POST https://api.manypost.com.br/v1/oauth/register`
  - **Description**: Autonomous agents presenting a cryptographically signed Identity Assertion can obtain scoped access immediately.
- **Flow 2: Verified Email Assertion (`verified_email`)**
  - **Registration Endpoint**: `POST https://api.manypost.com.br/v1/oauth/register`
  - **Description**: Agents operating on behalf of a registered manypost user submit a `verified_email` JWT assertion signed by the user or SSO provider.
- **Flow 3: Anonymous & Sandbox Access (`anonymous`)**
  - **Registration Endpoint**: `POST https://api.manypost.com.br/v1/oauth/register-sandbox`
  - **Description**: For non-destructive operations (e.g., querying pricing tiers, testing scheduled posts in sandbox).

---

## 3. Credential Usage & Security Headers

When authenticating requests against protected endpoints (`https://api.manypost.com.br/v1/*`), agents MUST include the credential using one of the following HTTP headers:

### Option 1: Bearer Access Token (OIDC / OAuth / Auth Login)
```http
Authorization: Bearer <your_access_token>
```

### Option 2: API Key Header (Granular API Keys)
```http
X-API-Key: <your_api_key>
```
*(Note: As specified in `/v1/api-keys`, the secret key in cleartext is only returned once upon creation).*

---

## 4. Supported API Scopes

When requesting access via `ID-JAG` or creating keys in `/v1/api-keys`, granular scopes MUST be specified:

| Scope | Description |
| :--- | :--- |
| `posts:read` | Consultar status, links de aprovação e histórico de grupos de publicações (`/v1/posts/*`). |
| `posts:write` | Criar, atualizar, cancelar ou republicar grupos de conteúdo em lote (`/v1/posts`). |
| `channels:read` | Listar canais, redes sociais conectadas e provedores oficiais disponíveis (`/v1/channels`). |
| `channels:write` | Iniciar conexão de novas redes sociais via OAuth/APIs oficiais (`/v1/channels/connect`). |
| `media:write` | Fazer upload de vídeos e imagens ou importar por URL para postagens (`/v1/media/*`). |
| `analytics:read` | Consultar relatórios de alcance, impressões e engajamento consolidado. |
| `webhooks:manage` | Cadastrar, listar e remover webhooks de notificação em tempo real (`/v1/webhooks`). |
| `mcp` | Autorização especial para transporte SSE via Model Context Protocol (`/api/mcp`). |

---

## 5. Token Revocation & Security Events

If an agent credential is compromised or decommissioned:
- **API Key Revocation**: `DELETE https://api.manypost.com.br/v1/api-keys/{id}`
- **OAuth Token Revocation**: `POST https://api.manypost.com.br/v1/oauth/revoke`
- **Session Logout**: `POST https://api.manypost.com.br/v1/auth/logout`

For questions or security disclosures regarding agent authentication, contact `security@manypost.com.br`.