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