# auth.md

Audience: AI agents and automated clients of Ada (tryada.site).

Ada lets an agent act **on a customer's behalf** (read-only) using OAuth 2.0 /
OpenID Connect with Dynamic Client Registration. There is **no** agent endpoint
that creates or modifies a website — site creation is a human, register-gated flow.

## Authorization server
- Issuer: https://tryada.site
- Discovery: https://tryada.site/.well-known/oauth-authorization-server (+ /.well-known/openid-configuration)
- Dynamic Client Registration (no secret needed; public PKCE clients): https://app.tryada.site/api/auth/oauth2/register
- Authorize: https://app.tryada.site/api/auth/oauth2/authorize · Token: https://app.tryada.site/api/auth/oauth2/token · JWKS: https://app.tryada.site/api/auth/jwks

## Protected resource (the customer's own data, read-only)
- Resource: https://tryada.site/api/v1
- Metadata (RFC 9728): https://tryada.site/.well-known/oauth-protected-resource
- Endpoints: `GET /api/v1/me`, `GET /api/v1/me/sites`, `GET /api/v1/me/billing`
- Send the access token as `Authorization: Bearer <token>`.

## Scopes
- `openid`
- `profile`
- `email`
- `sites:read`
- `billing:read`

## How to connect
1. Register a client at the register_uri (or via the discovery `registration_endpoint`).
2. Run the authorization-code + PKCE flow; the customer logs in and consents.
3. Exchange the code at the token endpoint for an access token scoped to the resource.
4. Call the protected endpoints above with the bearer token.

## Managing access
The customer can review and revoke every agent they've authorized at
https://app.tryada.site/settings/connected-agents (signed-in). Revoking deletes that agent's tokens immediately.

```json
{
  "agent_auth": {
    "skill": "https://tryada.site/auth.md",
    "register_uri": "https://app.tryada.site/api/auth/oauth2/register",
    "identity_endpoint": "https://app.tryada.site/api/auth/oauth2/register",
    "claim_uri": "https://app.tryada.site/settings/connected-agents",
    "authorization_servers": [
      "https://tryada.site"
    ],
    "scopes_supported": [
      "openid",
      "profile",
      "email",
      "sites:read",
      "billing:read"
    ],
    "identity_types_supported": [
      "anonymous"
    ],
    "anonymous": {
      "credential_types_supported": [
        "none"
      ],
      "claim_uri": "https://app.tryada.site/settings/connected-agents"
    },
    "credential_types_supported": [
      "bearer"
    ]
  }
}
```