# auth.md

Audience: AI agents and automated clients of Duqqan (duqqan.app).

Duqqan lets an agent act **on a customer's behalf** using OAuth 2.0 / OpenID Connect
with Dynamic Client Registration: it can read the customer's sites and plan and, with
the customer's consent, edit a site's draft and publish it through the MCP server.
There is **no** agent endpoint that creates a website — site creation is a human,
register-gated flow.

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

## Protected resource (the customer's own data)
- Resource: https://duqqan.app/api/v1
- Metadata (RFC 9728): https://duqqan.app/.well-known/oauth-protected-resource
- REST endpoints (read-only): `GET /api/v1/me`, `GET /api/v1/me/sites`, `GET /api/v1/me/billing`
- MCP server (Streamable HTTP): `https://duqqan.app/api/mcp` — the account tools, with the same token
- Send the access token as `Authorization: Bearer <token>`.

## Scopes
- `openid`
- `profile`
- `email`
- `offline_access`
- `sites:read`
- `billing:read`
- `sites:write`
- `sites:publish`

`sites:read` lets the MCP tools `list_my_sites`, `get_site`, `read_section`, `list_photos`
and `review_changes` read a site: its pages, sections, header and footer, languages, photo library,
and what a publish would change. `sites:write` lets `edit_text`, `set_section_visible`,
`add_photo_from_url` and `set_section_photo` change words, sections and photos **in the draft**
— visitors see nothing until the draft is published. `sites:publish` lets `publish_site` make
the draft live; it is a separate permission the customer can withhold. `set_page_seo` (a page's
search title and description) needs both, and is live at once. The REST API above stays read-only
whatever the token holds.

`sites:write` and `sites:publish` are granted only to a client whose **every** registered
redirect URI is `https` on `claude.ai`, `claude.com` or `chatgpt.com`, or `http` on
`localhost`, `127.0.0.1` or `[::1]` — the only `http` hosts registration accepts — on any port;
authorize lets such a client come back on a port other than the one it registered. A
`*.localhost` name (`http://foo.localhost/…`) is not a loopback address here, and a
custom-scheme redirect (`cursor://…`) is not eligible either. Any other client may ask for them; the consent screen
offers it the other scopes only, and a consent that tries to grant one is refused with
`invalid_scope`.

Access ends when the customer revokes it under Your account › AI assistants in their Duqqan
panel, or changes their sign-in email —
which disconnects every agent. Without `offline_access` it also ends at once when the customer
signs out of the browser session that approved it: the agent's tokens carry that session's `sid`.
Without `offline_access` there is no refresh token either: an agent signs in again when its access
token expires, after an hour. With it, a refresh token lasts 30 days and
each refresh issues a new one for another 30 days, so an agent that has not refreshed for 30 days
signs in again.

## 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 and the MCP server above with the bearer token.

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

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