# Sites

A site is an app or website that lets people in your organization sign in with Known and read 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 read.
2. A person opens the site and signs in with Known.
3. The site reads 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.

Sites can read wikis but can't write to them.

## 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.

`--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>:read` 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 start with the wiki's name:

```
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. |
| `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 read only the attached wikis they have access to.

### Which plans include sites?

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