# Vedastro auth.md

You are an AI agent. This document describes how automated agents discover, register, authenticate, and interact with Vedastro APIs (https://vedastro.guru).

Vedastro supports the **auth.md** agent registration standard and RFC 9728 OAuth Protected Resource Metadata. Autonomous agents can register programmatically, assert identity, or register anonymously and claim credentials.

---

## Agent Audience

This specification is intended for autonomous AI agents, multi-agent systems, client SDKs, and automated workflows requiring programmatic access to Vedastro services:
- Vedic birth chart calculation (Kundli)
- Kundli matching and relationship compatibility (Dampatya Match / Guna Milan)
- Palmistry analysis and reflection
- Behavioral assessments and personalized Vedic astrology guidance
- Transit analysis (Sade Sati) and Panchang calendar data

---

## Machine-Readable Discovery Endpoints

Vedastro publishes standard discovery documents for zero-human-touch onboarding:

- **OAuth Protected Resource Metadata (PRM, RFC 9728)**:
  `https://vedastro.guru/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata (RFC 8414 + agent_auth)**:
  `https://vedastro.guru/.well-known/oauth-authorization-server`
- **RFC 9727 API Catalog**:
  `https://vedastro.guru/.well-known/api-catalog`
- **OpenAPI 3.1 Specification**:
  `https://vedastro.guru/openapi.json`
- **Agent Skill & Auth Documentation**:
  `https://vedastro.guru/auth.md`

When calling an unauthenticated API endpoint, the server responds with:
```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://vedastro.guru/.well-known/oauth-protected-resource"
```

---

## Registration & Provisioning Endpoints

Agents can register, claim identity, exchange tokens, and manage revocation at the following endpoints:

- **Agent Registration (`register_uri`)**:
  `POST https://vedastro.guru/agent/auth` (alias: `POST https://vedastro.guru/api/v2/agent/auth`)
- **Identity Claim (`claim_uri`)**:
  `POST https://vedastro.guru/agent/claim` (alias: `POST https://vedastro.guru/api/v2/agent/claim`)
- **Token Exchange (`token_endpoint`)**:
  `POST https://vedastro.guru/oauth/token` (alias: `POST https://vedastro.guru/api/v2/auth/token`)
- **Credential Revocation (`revocation_uri`)**:
  `POST https://vedastro.guru/agent/revoke` (alias: `POST https://vedastro.guru/oauth/revoke`)

> **Note**: Passive security scanners should inspect the discovery documents rather than probing `POST /agent/auth` to avoid unintended account creation or notification dispatch.

---

## Supported Registration & Authentication Methods

Vedastro supports three registration flows:

### 1. ID-JAG (Identity Assertion JWT Authorization Grant)
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `urn:ietf:params:oauth:token-type:id-jag`
- **Credential Types**: `bearer_token`, `api_key`
- **Revocation URI**: `https://vedastro.guru/agent/revoke`
- **Events Supported**: `revocation`, `https://schemas.workos.com/events/agent/auth/identity/assertion/revoked`
- **Flow**:
  1. The agent obtains an ID-JAG assertion signed by a trusted identity provider (IdP).
  2. Audience (`aud`) MUST be set to `https://vedastro.guru`.
  3. Submit the assertion to `POST https://vedastro.guru/agent/auth` with payload:
     ```json
     {
       "identity_type": "identity_assertion",
       "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
       "assertion": "<JWT>"
     }
     ```
  4. Receive a scoped bearer access token and credential expiry details.
  5. Upstream revocation events (`revocation`) are processed per RFC 8935 push delivery.

### 2. Verified Email
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `verified_email`
- **Credential Types**: `bearer_token`, `api_key`
- **Claim URI**: `https://vedastro.guru/agent/claim`
- **Flow**:
  1. Agent presents a verified email assertion or requests email validation.
  2. POST to `POST https://vedastro.guru/agent/auth` with payload:
     ```json
     {
       "identity_type": "identity_assertion",
       "assertion_type": "verified_email",
       "email": "agent@example.com"
     }
     ```
  3. The service issues a pending claim session and returns a `claim_uri` (`https://vedastro.guru/agent/claim`).
  4. Once confirmed via out-of-band verification or claim code, the agent redeems the credential for an access token.

### 3. Anonymous Self-Registration
- **Identity Type**: `anonymous`
- **Credential Types**: `bearer_token`, `api_key`
- **Claim URI**: `https://vedastro.guru/agent/claim`
- **Flow**:
  1. Agent self-registers without initial identity credentials.
  2. POST to `POST https://vedastro.guru/agent/auth` with payload:
     ```json
     {
       "identity_type": "anonymous",
       "client_name": "MyAgent/1.0"
     }
     ```
  3. Receives guest-tier scoped credentials (e.g. read-only rate-limited astrology calculations).
  4. When the human user takes ownership, the agent binds to a user profile by submitting a verification token to `POST https://vedastro.guru/agent/claim`.

---

## Credential Use & Scopes

### Sending Credentials
Send your issued access token in the `Authorization` HTTP header with the `Bearer` scheme:
```http
Authorization: Bearer <access_token>
```
Alternative authentication via API key header is supported on designated calculation endpoints:
```http
X-API-Key: <api_key>
```

### Supported Scopes
- `astrology:read`: Calculate planetary positions, Dashas, transits, and Panchang.
- `kundli:read`: Generate birth charts, divisional charts, and interpretations.
- `compatibility:read`: Compute Ashtakoota / Guna Milan compatibility analysis.
- `palmistry:read`: Access palmistry analysis and landmark processing.
- `read`: General read-only access to published reference data and guides.
- `write`: Submit assessment responses and user profile state.

### Revocation
To revoke an issued credential, POST the token to `POST https://vedastro.guru/agent/revoke`:
```http
POST /agent/revoke HTTP/1.1
Host: vedastro.guru
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "token": "<access_token>",
  "token_type_hint": "access_token"
}
```