# auth.md

You are an AI agent.  ArloPlus supports **form-based agent registration**
for accessing protected APIs on behalf of a user.

## Step 1 — Discover

Protected Resource Metadata is published at:

```
GET https://arloplus.com/.well-known/oauth-protected-resource
```

This returns the resource server description, supported scopes, and the
authorization server URL where registration happens.

## Step 2 — Register

ArloPlus uses a simplified registration flow — **no OAuth 2.0 token exchange**.
Agents authenticate by submitting the user's credentials via form POST and
receiving a session cookie.

### Registration endpoint

```
POST https://arloplus.com/register
Content-Type: application/x-www-form-urlencoded

name=<display name>&email=<user email>&password=<password>&confirm_password=<password>
```

A successful registration returns a 302 redirect to the workspace.  The agent
should capture the `Set-Cookie` header from the response and include the session
cookie on subsequent API requests.

**Validation rules:**
- `name`: 2–100 characters
- `email`: valid email, must be unique
- `password`: minimum 6 characters
- `confirm_password`: must match `password`

CSRF protection is enabled — include the `csrf_token` from the registration
page's `<meta name="csrf-token">` in a `X-CSRFToken` header or `csrf_token`
form field.

## Step 3 — Authenticate

```
POST https://arloplus.com/login
Content-Type: application/x-www-form-urlencoded

email=<user email>&password=<password>&csrf_token=<token>
```

A successful login returns a 302 redirect with a session cookie.  Extract the
`Set-Cookie` header and include the `session` cookie on all subsequent API
requests.

**Error response:** 200 with `flash` message "Invalid email or password."
rendered in the login page HTML.

## Step 4 — Use the session cookie

Present the session cookie on every API request:

```
GET https://arloplus.com/api/sessions
Cookie: session=<session cookie value>
```

The session is valid for 24 hours.  Single-session enforcement may invalidate
older sessions when a new login occurs.

## Supported credential types

| Type | How to obtain | How to present |
|------|--------------|----------------|
| `session_cookie` | Form POST to `/login` | `Cookie: session=...` header |

## Identity types supported

- **`service_auth`** — email + password form-based registration and login.
  Agents register a new account or log into an existing one on the user's
  behalf using the user's credentials.

## Scopes

ArloPlus does not use OAuth scopes.  Access is determined by the authenticated
user's account type (free, premium) and token limits configured per-account.

## Revocation

To end a session, POST to `/logout`.  This invalidates the session cookie
server-side.

## API reference

Full API documentation is available in the API catalog:

```
GET https://arloplus.com/.well-known/api-catalog
```

## Notes

- Agentic registration (ID-JAG, claim ceremonies, JWT-bearer grants per the
  full Auth.md protocol) is **not yet supported**.  This document describes
  the form-based auth path only.
- All `/api/*` endpoints require authentication via session cookie.
- Rate limits apply — respect 429 responses with `Retry-After` headers.
- TLS is required; all requests must use HTTPS.