# WhatsApp Automation Platform auth.md

This document specifies authentication, authorization, and agent registration discovery for AI agents, automated tools, and developers interacting with the WhatsApp Automation Platform.

## Audience

This discovery document is intended for:
- Automated AI agents and tool callers
- Third-party client applications and bot integrations
- Developers integrating WhatsApp and SMM automation workflows

## Machine-Readable OAuth Discovery

- **OAuth Protected Resource Metadata (PRM)**: `/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata**: `/.well-known/oauth-authorization-server`
- **RFC 9727 API Catalog**: `/.well-known/api-catalog`

## Registration and Provisioning

Agents and client applications can provision accounts or credentials using the following endpoints:

- **Register Endpoint**: `POST /api/auth/register`
  - Body: `{"username": "<username>", "email": "<email>", "password": "<password>"}`
  - Response: Account registration confirmation and credentials.
- **Login / Token Endpoint**: `POST /api/auth/login`
  - Body: `{"username": "<username_or_email>", "password": "<password>"}`
  - Response: `{"access_token": "<jwt_token>", "token_type": "bearer", "user": {...}}`

## Authentication Methods

1. **Bearer Token (JWT)**
   - Header: `Authorization: Bearer <access_token>`
   - Required for protected `/api/user/*` and `/api/admin/*` endpoints.

2. **API Key / Secret Header**
   - Header: `X-API-Key: <key>` or `Authorization: Bearer <key>`
   - Supported for automated provider synchronization and webhook delivery.

## Supported Scopes

- `user` — Access user account, WhatsApp device connections, message logs, and orders.
- `admin` — Full administrative control and provider management.
- `devices` — Connect, disconnect, and monitor WhatsApp sessions.
- `orders` — Create and track automation tasks and orders.
- `whatsapp` — Send and receive WhatsApp messages via connected instances.

## Agent Auth & Flow Metadata

- **Standard**: [Auth.md Agent Registration Discovery](https://isitagentready.com/.well-known/agent-skills/auth-md/SKILL.md)
- **Registration URI**: `/api/auth/register`
- **Supported Identity Types**:
  - `identity_assertion` (Assertion type: `urn:ietf:params:oauth:token-type:id-jag`, `verified_email`)
  - `verified_email`
  - `anonymous`
- **Token Type**: Bearer token (`header`)