ory / ory/docs

Keto documentation seems outdated and incomplete

Open
#2,309 1 comment 0 reactions 1 assignee View on GitHub

@unatasha8 is already working on this.

Since Nov 20, 2025.

bug
Dominant language
TypeScript
Stars
161
Forks
1.9k
PR merge metrics
No merged PRs in 30d

Description

Preflight checklist
Describe the bug

Hi! The list I'm about to share might seem like a lot of complaining, but I'm fresh to Keto (and Ory in general) and I figured it might be worth sharing this perspective from an outsider.

To sum it up, the impression the docs give me after spending an afternoon combing through them is that Keto doesn't seem mature enough to depend upon, which I'm sure is something that is untrue and an impression you'd like to avoid. I hope I don't come across as too blunt, this is not a value judgment nor is it intended as a snipe.

Besides #2106, the docs suffer from the following issues:

  • There is no explanation on how to apply your permission model to a keto instance. You might write a your permissions.ts, but what then?
  • There is no documentation on how to update a permission model either, nor best practices in doing so.
  • The configuration options are poorly documented
    • $schema seems to assume you know what it's for.
    • Listen files are not documented, nor is their use-case
  • There is no minimal configuration that will allow you to get started with your own project (apart from if you dig into the outdated cat-videos-example), leaving the user confused on which options are actually required.
  • The configuration editor is broken, all fields are read-only (at least in Firefox)
  • Installation section seems to be more of a "How to get binaries" section. Nowhere does it mention, for example, that database migrations need to be ran before starting the main server
  • macOS instructions seem to suggest the keto executable name is undefined
  • Under Self-Hosted->Reference->SDK, there are inexplicably 2 entries. "Ory Keto SDK" and "Go".
  • There is documentation and some code samples for List API and Expand API, but not the permission check itself]
  • It is unclear whether the Zanzibar is actually used anywhere in Keto itself and needs to be learned, or if it's just present in some of the documentation, since it doesn't seem to be used in the API at all and it isn't intuitive to read.
Reproducing the bug

Try to get started with Keto as a developer without prior experience.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.