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