# Abracadabra auth.md

> Agent Registration & Authentication Discovery for [Abracadabra](https://tryabracadabra.com)

Abracadabra provides conversation-layer analytics for AI agents. This document describes machine-readable and autonomous authentication, registration, and discovery interfaces per the Auth.md specification, RFC 9728 (OAuth Protected Resource Metadata), and RFC 8414 (OAuth Authorization Server Metadata).

---

## 1. Agent Audience

This interface is designed for autonomous AI agents, coding assistants, workflow bots, and agent frameworks seeking programmatic access to Abracadabra analytics, access request workflows, and platform telemetry.

- **Audience Identifier**: `https://tryabracadabra.com`
- **Resource Server**: `https://tryabracadabra.com`
- **Authorization Server**: `https://tryabracadabra.com`

---

## 2. Discovery Documents

Agents should consult the following RFC-compliant discovery endpoints:

- **OAuth Protected Resource Metadata (PRM, RFC 9728)**:
  `GET /.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata (RFC 8414)**:
  `GET /.well-known/oauth-authorization-server`
- **OpenID Connect Discovery**:
  `GET /.well-known/openid-configuration`
- **API Catalog (RFC 9727)**:
  `GET /.well-known/api-catalog`
- **Machine-Readable LLM Guides**:
  `GET /llms.txt` and `GET /llms-full.txt`
- **Pricing & Tier Specifications**:
  `GET /pricing.md`

---

## 3. Supported Authentication & Registration Methods

Abracadabra supports three agent registration and authentication flows declared in our Authorization Server metadata (`agent_auth` block):

### Method A: Anonymous Exploration (`anonymous`)
For zero-friction agent exploration and sandbox telemetry readouts.
- **Identity Type**: `anonymous`
- **Credential Type**: `bearer`
- **Claim Endpoint**: `POST https://tryabracadabra.com/api/agent/anonymous`
- **Default Scopes**: `read`
- **Token Format**: Ephemeral scoped bearer token passed via standard `Authorization: Bearer <token>` header.

### Method B: Verified Email Registration (`verified_email`)
For teams deploying agents on behalf of organizations or customers requesting production access.
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `verified_email`
- **Claim / Request Endpoint**: `POST https://tryabracadabra.com/api/request-access`
- **Credential Type**: `bearer`
- **Parameters**: `{"email": "agent@domain.com", "name": "Agent Name", "agent": "Framework / Use Case"}`
- **Granted Scopes**: `read`, `request_access`

### Method C: ID-JAG Cryptographic Assertion (`urn:ietf:params:oauth:token-type:id-jag`)
For high-assurance cryptographic agent-to-agent delegation using JWT-based Identity Assertion Grants.
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `urn:ietf:params:oauth:token-type:id-jag`
- **Token Exchange Endpoint**: `POST https://tryabracadabra.com/api/agent/claim`
- **Revocation Endpoint**: `POST https://tryabracadabra.com/api/agent/revoke`
- **Supported Events**: `revocation`

---

## 4. Scopes & Permissions

| Scope | Description |
| :--- | :--- |
| `read` | Read public pricing models, benchmarks, and platform documentation |
| `request_access` | Submit programmatic access and waitlist onboarding requests |

---

## 5. Credential Usage

All authenticated API requests must include the bearer token in the HTTP `Authorization` request header:

```http
GET /api/v1/metrics HTTP/1.1
Host: tryabracadabra.com
Authorization: Bearer <token>
Accept: application/json
```