# Sites

A site is an app or website that lets people in your organization sign in with Known and work with your wikis. For example, you can build an investor portal from a `fundraising` wiki, or a customer portal from a project wiki. Each person sees only the wikis they have access to.

## How sites work

1. You register the site in Known and attach the wikis it can use.
2. A person opens the site and signs in with Known.
3. The site reads, and where allowed writes, the attached wikis on that person's behalf.

Known checks every request. If you detach a wiki or remove someone from the site, their next request fails.

A wiki is attached for reading and writing, or for reading only. On a wiki attached for writing, a site can write pages and records wherever the signed-in person may; it can't move or remove pages, change page settings or add notes.

## Register a site

In the browser, go to **Sites** and register a new site. Or use the CLI:

```
known acme sites create "Investor portal" --redirect https://portal.acme.com/callback --site https://portal.acme.com
known acme sites attach <client-id> fundraising
```

Admins and wiki owners can register sites. Attaching a wiki requires owner access to it or an admin role.

An agent connected to Known (see [Connect an agent](https://known.info/docs/connect-agent)) can do the same without leaving the chat: `site_create` registers the site, `site_attach` attaches a wiki (pass `capabilities: ["read"]` for read-only), `site_detach` detaches one, and `site_publish` puts it live. A published site picks up an attach or detach the next time it is published.

`--redirect` sets the address Known returns people to after they sign in. It must be an exact `https` address, or an `http` address on `localhost` during development.

By default, every member can use the site. To limit it to specific people and teams, pass `--user user:<id>` or `--user team:<id>`.

## Sign people in

Sites use OAuth 2.0 with the authorization code flow and PKCE (S256), so you can use any standard OAuth library. Sites don't use a client secret. You can find these values in the site's **Develop** tab:

| Value | |
|---|---|
| Authorization URL | `https://known.info/authorize` |
| Token URL | `https://rpc.known.info/oauth/token` |
| Client ID | Your site's client ID, starting with `app_` |
| Scope | `wiki:<name>` for each attached wiki, separated by spaces |

Access tokens expire after one hour. Each refresh token can be used once. To sign a person out, call `POST https://rpc.known.info/oauth/revoke`.

## Read wikis

Send JSON-RPC 2.0 requests to the RPC host with the person's access token. Paths are the wiki's name, a colon, then the page (`fundraising:round`):

```
curl -s https://rpc.known.info/rpc \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <access_token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"wiki.read","params":{"path":"fundraising:round"}}'
```

| Method | Returns |
|---|---|
| `site.whoami` | Who is signed in, and their access to each wiki. |
| `wiki.read`, `wiki.tree`, `wiki.search` | Pages. |
| `wiki.records`, `wiki.get` | Records. |
| `wiki.write`, `wiki.edit` | Write a page's content (on a wiki attached for writing). |
| `wiki.set`, `wiki.del` | Write or delete a record (on a wiki attached for writing). |
| `site.watch` | A live stream of changes. |

For every method and parameter, see the [RPC reference](https://rpc.known.info/rpc). A `GET` request to `https://rpc.known.info/rpc` with a person's access token returns your site's own reference, including its wikis and that person's access.

## FAQ

### Who can use my site?

Members of your organization who are allowed to use the site. By default, that's every member. They can use only the attached wikis they have access to, and only as far as their own access goes.

### Which plans include sites?

Every plan. `site.watch` requires live updates on your plan. Without them, poll `wiki.changes`.