1. Project Overview & Quickstart (ory/kratos) Copy Chapter

File: README.md Copy Chapter

[Chat](https://www.ory.com/chat) · [Discussions](https://github.com/ory/kratos/discussions) · [Newsletter](https://www.ory.com/l/sign-up-newsletter) · [Docs](https://www.ory.com/docs/) · [Try Ory Network](https://console.ory.sh/) · [Jobs](https://www.ory.com/jobs/)

Ory Kratos is an API first identity and user management system for cloud native
applications. It centralizes login, registration, recovery, verification, and
profile management flows so your services consume them instead of reimplementing
them.

Table of contents

• What is Ory Kratos?
  • Why Ory Kratos
• Migrating from Auth0, Okta, and similar providers
• Deployment options
  • Use Ory Kratos on the Ory Network
  • Self-host Ory Kratos
• Quickstart
  • Who is using it?

What is Ory Kratos? Copy Chapter

Ory Kratos is an API first identity and user management system that follows
cloud architecture best practices.
It focuses on core identity workflows that almost every application needs:

• Self service login and registration
• Account verification and recovery
• Multi factor authentication
• Profile and account management
• Identity schemas and traits
• Admin APIs for lifecycle management

We recommend starting with the
Ory Kratos introduction docs to learn more
about its architecture, feature set, and how it compares to other systems.

Why Ory Kratos Copy Section

Ory Kratos is designed to:

• Remove identity logic from your application code and expose it over HTTP APIs
• Work well with any UI framework through browser based and native app flows
• Scale to large numbers of identities and devices
• Integrate with the rest of the Ory stack for OAuth2, OpenID Connect, and
  access control
• Fit into modern cloud native environments such as Kubernetes and managed
  platforms

Migrating from Auth0, Okta, and similar providers Copy Chapter

If you are migrating from Auth0, Okta, or another identity provider that uses
OAuth2 / OpenID Connect based login, consider using Ory Hydra + Ory Kratos
together:

• Ory Hydra acts as the OAuth2 and OpenID Connect provider and can replace
  most authorization server and token issuing capabilities of your existing IdP.
• Ory Kratos provides identity, credentials, and user-facing flows (login,
  registration, recovery, verification, profile management).

This combination is often a drop-in replacement for OAuth2 and OpenID Connect
capabilities at the protocol level. In practice, you update client configuration
and endpoints to point to Hydra, migrate identities into Kratos, and keep your
applications speaking the same OAuth2 / OIDC protocols they already use.

Deployment options Copy Chapter

You can run Ory Kratos in two main ways:

• As a managed service on the Ory Network
• As a self hosted service under your own control, with or without the Ory
  Enterprise License

Use Ory Kratos on the Ory Network Copy Section

The Ory Network is the fastest way to use Ory
services in production. Ory Identities is powered by the open source Ory
Kratos server and is API compatible.

The Ory Network provides:

• Identity and credential management that scales to billions of users and
  devices
• Registration, login, and account management flows for passkeys, biometrics,
  social login, SSO, and multi factor authentication
• Prebuilt login, registration, and account management pages and components
• OAuth2 and OpenID Connect for single sign on, API access, and machine to
  machine authorization
• Low latency permission checks based on the Zanzibar model with the Ory
  Permission Language
• GDPR friendly storage with data locality and compliance in mind
• Web based Ory Console and Ory CLI for administration and operations
• Cloud native APIs compatible with the open source servers
• Fair, usage based pricing

Sign up for a
free developer account
to get started.

Self-host Ory Kratos Copy Section

You can run Ory Kratos yourself for full control over infrastructure,
deployment, and customization.

The install guide explains how to:

• Install Kratos on Linux, macOS, Windows, and Docker
• Configure databases such as PostgreSQL, MySQL, and CockroachDB
• Deploy to Kubernetes and other orchestration systems
• Build Kratos from source

This guide uses the open source distribution to get you started without license
requirements. It is a great fit for individuals, researchers, hackers, and
companies that want to experiment, prototype, or run unimportant workloads
without SLAs. You get the full core engine, and you are free to inspect, extend,
and build it from source.

If you run Kratos as part of a business-critical system, for example login and
account recovery for all your users, you should use a commercial agreement to
reduce operational and security risk. The Ory Enterprise License (OEL)
layers on top of self-hosted Kratos and provides:

• Additional enterprise features that are not available in the open source
  version such as SCIM, SAML, organization login ("SSO"), CAPTCHAs and more
• Regular security releases, including CVE patches, with service level
  agreements
• Support for advanced scaling, multi-tenancy, and complex deployments
• Premium support options with SLAs, direct access to engineers, and onboarding
  help
• Access to a private Docker registry with frequent and vetted, up-to-date
  enterprise builds

For guaranteed CVE fixes, current enterprise builds, advanced features, and
support in production, you need a valid
Ory Enterprise License and access
to the Ory Enterprise Docker registry. To learn more,
contact the Ory team.

Quickstart Copy Chapter

Install the Ory CLI and
create a new project to try Ory Identities.

# Install the Ory CLI if you do not have it yet:
bash <(curl https://raw.githubusercontent.com/ory/meta/master/install.sh) -b . ory
sudo mv ./ory /usr/local/bin/

# Sign in or sign up
ory auth

# Create a new project
ory create project --create-workspace "Ory Open Source" --name "GitHub Quickstart"  --use-project
ory open ax login

Who is using it? Copy Section

The Ory community stands on the shoulders of individuals, companies, and
maintainers. The Ory team thanks everyone involved - from submitting bug reports
and feature requests, to contributing patches and documentation. The Ory
community counts more than 50.000 members and is growing. The Ory stack protects
7.000.000.000+ API requests every day across thousands of companies. None of
this would have been possible without each and everyone of you!

The following list represents companies that have accompanied us along the way
and that have made outstanding contributions to our ecosystem. If you think
that your company deserves a spot here, reach out to
[email protected] now!

Many thanks to all individual contributors

File: docs/README.md Copy Chapter

Documentation

Please find the documentation at
www.ory.com/docs/kratos.

To contribute to the documentation, please head over to:
github.com/ory/docs/tree/master/docs/kratos

File: persistence/sql/README.md Copy Chapter

SQL Migrations

Migrations consist of one up and one down file.
To create these SQL migrations, copy the last migration in ./persistence/sql/migrations/sql and change the timestamp to the current timestamp and the name to the desired name.

If some logic is different for one of the database systems, add the id after the name to the file name.
The content of that file will override the content of the "general" file for that particular DB system.

Example:

20220802103909000000_courier_send_count.up.sql
and
20220802103909000000_courier_send_count.down.sql

With for example cockroach specific behavior:

20220802103909000000_courier_send_count.cockroach.up.sql
and
20220802103909000000_courier_send_count.cockroach.down.sql

Replace cockroach with mysql, postgres or sqlite if applicable.

Old Way Copy Chapter

To create SQL migrations, target each database individually and run

$ dialect=mysql  # or postgres|cockroach|sqlite
$ name=
$ ory dev pop migration create -d=$dialect ./persistence/sql/migrations/templates $name
$ soda generate sql -e mysql -c ./persistence/sql/.soda.yml -p ./persistence/sql/migrations/templates [name]
$ soda generate sql -e sqlite -c ./persistence/sql/.soda.yml -p ./persistence/sql/migrations/templates [name]
$ soda generate sql -e postgres -c ./persistence/sql/.soda.yml -p ./persistence/sql/migrations/templates [name]
$ soda generate sql -e cockroach -c ./persistence/sql/.soda.yml -p ./persistence/sql/migrations/templates [name]

and remove the sqlite part from the newly generated file to create a SQL migrations that works with all
aforementioned databases.

Rendering Migrations Copy Chapter

Because migrations needs to be backwards compatible, and because fizz migrations might change, we render
fizz migrations to raw SQL statements using make migrations-render.

The concrete migrations being applied can be found in ./migrations/sql.

2. Official Technical Reference & Guides (ory/docs) Copy Chapter

Ory Documentation

[Chat](https://slack.ory.com) | [Newsletter](https://www.ory.com/l/sign-up-newsletter) [Documentation](https://www.ory.com/docs/) | [Support this project!](https://opencollective.com/ory) [Work in Open Source, Ory is hiring!](https://www.ory.com/jobs/)

• Overview
• Style guide
  • Grammar and style
    • Lists
    • Headings
  • Formatting
    • Document front matter
    • Bolding, 'code formatting'
    • Linking
    • Code blocks
    • Placeholders and dummy data
    • UI references
    • Diagrams
  • Import & reference content
    • Markdown partials
    • Code snippets
      • From GitHub
      • From this repository
  • Screenshots and videos
    • Compressing images
    • Recording and compressing videos
  • Ory Console
    • Navigate to Ory Console Pages
  • Testing
    • Redirects
      • How to add a redirect
  • Formatting documentation
  • Adding content to "Examples" page
  • CLI and API reference - auto-generated content

Overview

Ory documentation is the single source of truth for usage, implementation,
configuration, and troubleshooting of the Ory Network and all projects of the
Ory Ecosystem. The documentation
is best consumed through the
Ory documentation portal.

To see the source code of each of the projects, visit the project repository:

• Ory Kratos
• Ory Hydra
• Ory Oathkeeper
• Ory Keto

Documentation of other Ory projects:

• Ory Kubernetes Helm Charts
• Ory Dockertest
• Ory SDKs

Style guide

This style guide outlines the most important rules and conventions that apply to
the Ory documentation. If there are no Ory-specific requirements or guidelines
for a given topic, refer to the
Microsoft Writing Style Guide
and follow the rules described there.

Grammar and style Copy Chapter

Ory documentation must be clear, concise, and unambiguous. To achieve that,
follow these simple rules:

1. Use active voice and present tense.
2. Always write in American English.
3. Use
   zero conditional
   when talking about the cause-and-effect in software behavior.
4. Use the right words to make sure that your message is clear and unambiguous.
   Don't use words like "should", "could", or "may".
5. Don't use phrasal verbs, colloquialisms, and jargon.
6. Don't refer to users in ways that imply their sex.
7. Don't use contractions of Latin origins such as e.g or i.e.
8. Remember to use articles (a, an, the) in your writing.
9. Use common contractions such as aren't, don't, doesn't to sound
   friendly and informal.

Lists Copy Section

Ory follows the
Microsoft Writing Style Guide list formatting guidelines.

• List items must begin with a capital letter unless there's a specific reason
  not to do that. For example, the item is a proper name that's not capitalized,
  a parameter, or a command wrapped in backticks (`).
• Don't use punctuation such as commas (,), semicolons (;), or conjunctions
  (and, or) at the end of list items.
• Use periods (.) only at the end of list items that are proper sentences,
  even very short ones.
• Make list items consistent in structure. For example, if one list item is a
  full sentence, make all list items full sentences. Don't use different
  structures for list items in a single list.
• Indent lines with 3 spaces to denote nested sub-items in lists. Indent text,
  code blocks, and images.
• When a bulleted list presents parallel items that each pair a label with an
  explanation, bold the label as a lead-in, followed by an em dash and the
  explanation. Use this pattern only when every bullet shares it. For example:
  • Fully managed infrastructure — Ory Network runs a global edge network
    with multi-region availability, automatic scaling, and high availability.
    You don't patch servers, rotate keys, or manage failover.
  • Predictable pricing — Usage-based billing with no per-seat fees, so cost
    scales with traffic rather than team size.

Headings Copy Section

• Use
  sentence case
  for headings.
• The highest heading level in documents is h2. Use h1 only when you
  override the document title.
• The lowest heading level in documents is h4. If you absolutely need to add
  more heading levels, don't go lower than h5.
• Avoid using symbols and special characters in headings.
• Leave one blank line before and after a heading.
• Don't use links in headings.
• Headings play an important role in SEO and searchability and make the document
  more scannable. Make your headings short and true to the content they
  introduce.

Formatting Copy Chapter

Write in Markdown. Don't mix HTML tags with
Markdown. Files with the .mdx extension use
JSX-extended Markdown (MDX).

Document front matter Copy Section

Add this front matter to every document you create:

---
id: excellent_feature
title: Learn how to use the excellent feature in your implementation
sidebar_label: Excellent feature
slug: excellent-feature-for-some-reason
---

• id is the document identifier that makes up the last part of the document
  URL. Try to come up with a short ID that accurately describes the content. IDs
  that use multiple words must use hyphens (-) to separate the words.
• title is the document title that’s displayed as the page header. Used by
  search engines when displaying search results. Try to make it descriptive so
  that it helps readers understand what the document is about at the first
  glance. If it comes out long(ish), you can overwrite it by adding a h1 in
  the very first line following the front matter. Use sentence case.
• sidebar_label represents the document title used in the sidebar (left
  navigation). Create a short document title that fits the sidebar width. Use
  sentence case.
• slug is an optional property that allows you to customize the document URL.
  Use it to create more meaningful, SEO-friendly URLs.
• description is a one-sentence summary of the page. Any document that appears
  as a card in a sidebar category (a generated category index) must set it,
  because Docusaurus derives the card text from createExcerpt, which only
  keeps the first physical line of the first paragraph and truncates at the
  source line wrap. Setting description gives you the full, intended card text
  and is also used by search engines. Keep it to one short sentence.

Bolding, 'code formatting' Copy Section

• Use only code and bold formatting. Don't use any other formatting.
• For inline code, wrap text in single backticks (`). For code blocks use
  three backticks (```)
• Use code formatting for:
  • Commands, for example ory --help
  • File names and paths, for example file.txt, ~/Desktop/git/docs
  • Environment variables, for example CUSTOM_ENV_VAR
• Use bold only when writing about user interface (UI) elements.

Linking Copy Section

• Link to external web pages using absolute links. Don't expose the link on its
  own. Instead, embed it in descriptive text. For example:

  text Copy

  Ory documentation uses [Prism syntax highlighting](https://prismjs.com/).

• Link to documents within this repository using relative links. When
  referencing the file, use the file name.

  text Copy

  [Some link](../path/to/file.mdx)

Code blocks Copy Section

• Always add a programming language identifier to code blocks. Ory documentation
  uses Prism syntax highlighting.

  text Copy

  ```json
  {some-JSON-code-here}
  ```

• For command line examples, use shell as the programming language identifier.
  Don't put $ before the command.

  text Copy

  ```shell
  ory get identities
  ```

• For Ory Permissions (Keto) relation tuples, use keto-relation-tuples
  language identifier, and for relationships use keto-relationships.

  text Copy

  ```keto-relation-tuples
  namespace:object#relation:subject
  // comment
  ```
  
  ```keto-relationships
  namespace:subject is relation of object
  is namespace:subject allowed to permission on object?
  // comment
  ```

• For multi-line commands, indent subsequent lines of the command with two
  spaces.

  text Copy

  ```shell
  curl --request GET -sL \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer {ORY_API_KEY}" \
    'https://{project-slug}.projects.oryapis.com/admin/identities/{identity_id}?include_credential=oidc'
  ```

Placeholders and dummy data Copy Section

Using placeholders and dummy data in code snippets and command examples is a
good way to ensure that users run commands in the context of their setups and,
as a result, achieve success faster. Additionally, this fabricated information
prevents leaking of sensitive data such as tokens or API keys.

Follow these rules when using placeholders and dummy data:

• Introduce placeholders and dummy data in curly brackets with a preceding $ so
  they can be used in bash commands.
• Use colons (-) or underscores (_) to separate multiple words, for example
  {ORY_SESSION_COOKIE} or {project-slug}.
• When referring to a project API URL or SDK URL, always use
  https://$PROJECT_SLUG.projects.oryapis.com.
• When referring to scenarios in which the user runs a custom domain, use
  https://ory.your-custom-domain.com.
• Always use short, but descriptive, verbal placeholders. Don't mix digits and
  letters to mimic the format of the data you mock.

UI references Copy Section

When talking about any user interface (UI) in the Ory documentation, follow
these rules:

• When referring to UI elements, always use the exact text associated with the
  given element.
• Format the name of the UI element you refer to in bold.
• Format any user input with code.

Example: In the Identity Model Schema box, type MyCustomIdentitySchema.

Diagrams Copy Section

Use Mermaid to create diagrams. You
can run the tool locally or use Mermaid Live Editor in
the browser. See the
Mermaid Cheatsheet
for a detailed description on how to use Mermaid.

To add a Mermaid diagram, use this mdx-code-block:

```mdx-code-block
import Mermaid from "@site/src/theme/Mermaid"
<Mermaid
  chart={`

{your-Mermaid-code}

`}
/>
```

Import & reference content Copy Chapter

Markdown partials Copy Section

If a certain piece of content must be re-used across multiple documents in the
exact form, it's a good idea to turn it into a partial. Thanks to that, you
maintain content in a single file, instead of multiple instances of the same
content in many docs.

Add partials to the _common directory.

To import a partial, use this mdx-code-block:

```mdx-code-block
import ExamplePartial from './_common/example.md'

<ExamplePartial />
```

TIP: Headings contained in partials aren't added to the Docusaurus table
of contents (ToC). To make sure users can access all headings through the ToC,
don't add headings to partials. Instead, add appropriate headings to the
document manually and introduce partials after them. To see an implementation
of this approach, look at
this file.

Code snippets Copy Section

From GitHub

Use
CodeFromRemote
to import code directly from GitHub.

Use this mdx-code-block:

```mdx-code-block
import CodeFromRemote from '@theme/CodeFromRemote'

<CodeFromRemote
  lang="js"
  link="https://github.com/ory/kratos-selfservice-ui-node/blob/master/src/middleware/simple.ts"
  src="https://raw.githubusercontent.com/ory/kratos-selfservice-ui-node/master/src/middleware/simple.ts"
  startAt="{CONTENT_FROM_CODE}"
  endAt="{CONTENT_FROM_CODE}"
/>
```

• lang specifies the programming language the code is in
• link is the file location displayed in the top part of the code block window
• src is the direct link used to import the code (optional)
• startAt , endAt are used to define where the imported snippet starts and
  ends (optional)

From this repository

```mdx-code-block
import CodeBlock from '@theme/CodeBlock'
import exampleJs from '!!raw-loader!./code-example.jsx'
import exampleGo from '!!raw-loader!./code-example.go'

<CodeBlock className="language-jsx">{exampleJs}</CodeBlock>
<CodeBlock className="language-go">{exampleGo}</CodeBlock>
```

Screenshots and videos Copy Chapter

• Use screenshots and videos sparingly. These resources tend to get out-of-date
  quickly and are cumbersome to maintain.
• Screenshots and videos must capture only the relevant parts of the screen.
• Screenshots and videos must capture UI elements in English. If you’re
  capturing parts of the browser UI in your work, make sure the UI is in
  English.
• Make an effort to get the screenshots and videos looking as clean as possible.
  Avoid situations where text fields suggest irrelevant inputs, avoid erratic
  mouse cursor movements and general chaos.
• You must add media to _static folders.
  • In the _static directory, each document that uses media has its own
    directory.
  • In the directory of the document, the files have numbers for names, for
    example, 1.png, 2.png, 3.png. The filenames should reflect the stage
    at which the media is used in the document. This means that the screenshot
    named 1.png will be used in line 70, while the diagram 2.svg will be
    used in line 100.

Compressing images Copy Section

Compress images you add to the documentation to keep the repository lean. You
can use pngquant.
Read this article to learn a trick to make your screenshots 80% smaller.

Recording and compressing videos Copy Section

We recommend using
Quicktime to record videos.
Follow these rules:

• Use 16:9 format with at least 1024 pixels of width. ffmpeg will scale it to
  the right size.
• Make sure that no history or auto-suggestions are visible.

After recording the video, convert the .mov file to mp4 and webm:

file="screencast.mov"

ffmpeg -i $file -an -c:v libvpx-vp9 -vf scale=1024:-1 -crf 30 -b:v 0 "${file%.*}".webm
ffmpeg -i $file -vcodec h264 -vf scale=1024:-1 -an "${file%.*}".mp4

Use this mdx-code-block to add the video to your document:

```mdx-code-block
import mp4 from './_static/screencast.mp4'
import webm from './_static/screencast.webm'
import VideoEmbed from '@site/src/components/VideoEmbed'

<VideoEmbed mp4={mp4} webm={webm} />
```

Ory Console Copy Chapter

Navigate to Ory Console Pages Copy Section

You can use the /current/ route to navigate users to their active Ory Network
project. For example, to access the Custom UI settings for the active Ory
Network project in the Console, you can link to:
https://console.ory.com/projects/current/ui

When referencing a page of the Ory Console, use the
<ConsoleLink route="project..." /> component in MDX files.

The component resolves the navigation section and page title for the given
route, and renders a standard markup for both, as well as the link with the
/current/ shortcut mentioned above:

<ConsoleLink route="project.activity.events" />

// becomes:
// Activity → Logs & Events in the [Ory Console](https://console.ory.com/current/projects/activity/events)

A list of all supported routes can be found here:
src/components/ConsoleLink/console-routes.ts.

Please note that the syntax is like accessing a path in a JS object, but as a
string. If the route you want to reference is found in the console-routes.ts
file in the following way:

{
  project: {
    activity: {
      events: {
        route: "/projects/[project]/activity/events",
      }
    }
  }
}

Use <ConsoleLink route="project.activity.events" /> to reference it.

To add a new route, you need to add an entry in
console-routes.ts
as well as
console-nav-data.ts.

Testing Copy Chapter

To test the documentation locally:

1. Clone this repository.
2. Navigate to the cloned repository and run npm install to install all
   dependencies.
3. Run the development server and test the changes you made using a fully
   operational version of the documentation portal that runs on your machine.
   Run npm run start.
4. Create a production build to check for any technical issues, such as invalid
   internal links. Run npm run build.

Redirects Copy Section

When the URL of a document changes, you must set up a redirect to preserve SEO
and prevent broken links. Without redirects, the original URL returns a 404
error, breaking existing links from external sites and causing search engines to
lose page authority.

The rule is: if the URL in the browser changes, add a redirect. If it doesn't,
no redirect is required.

Filenames don't always determine URLs. Ory documentation uses numbered prefixes
in filenames and sets URLs explicitly in the front matter. Renaming with no
other changes doesn't require a redirect because the final URL stays the same.

You must add a redirect when you

• change the slug or id property in the document front matter
• delete a document
• move a document to a different directory (if it changes the URL path)

How to add a redirect

Add redirects to the vercel.json file in the repository root. Use this format:

{
  "redirects": [
    {
      "source": "/docs/old-path",
      "destination": "/docs/new-path",
      "permanent": false
    }
  ]
}

• Start with permanent: false (302 redirect) until you confirm the redirect
  works in the preview or production environment.
• Change to permanent: true (301 redirect) after you verify the redirect
  functions correctly.
• Test the redirect in the Vercel preview deployment before merging.

Formatting documentation Copy Chapter

All documents and other files in this repository must be formatted with Prettier
using the Ory Prettier styles.

To format all relevant files, run these commands from the main directory of the

make format
git commit -a -m "chore: format"
git push

For a better workflow, install the Prettier plugin for your editor:

• VSCode Prettier plugin
• IntelliJ Prettier plugin

Adding content to "Examples" page Copy Chapter

The Quickstart overview
provides an overview of Ory quickstarts. To add a new example or modify existing
entries:

1. Open examples-content.tsx in src/pages/_assets/.

2. Copy the following snippet and append it to the correct array (either
   official, community, or self-hosting examples):

   tsx Copy

   {
         title: "Protect a Page with Login: NextJs/React", //Your example title goes here
         language: "typescript",                           //The main programming language of your example
         author: "ory",                                    //The author's GitHub handle
         tested: true,                                     //Is the example in ory/examples or ory/docs and has automated tests?
         repo: "https://github.com/ory/docs/tree/master/code-examples/protect-page-login/nextjs", //The repo containing the example code
         docs: "https://www.ory.sh/docs/guides/protect-page-login/next.js",                       //Documentation for the example, can be README, blog article or similar
       },

   • language can be one of: dart, django, docker, erlang, flutter, go, java,
     javascript, kotlin, kubernetes, nextjs, nodejs, ory, php, python, react,
     rescript, svelte, typescript, vue

3. Open a pull request with your changes.

CLI and API reference - auto-generated content Copy Chapter

Ory documentation contains auto-generated content such as CLI and API
references. Documents of this type are generated from source code and are pushed
to this repository by an automated job.

As such, editing any of these documents in the Ory documentation repository
isn't the way to change or fix this content. Any changes you make will be
overwritten by the next push that follows the generation process.

Instead, find the lines in question in the source code of the Ory projects and
edit them there. For example, if you want to edit the documentation of the Ory
Kratos CLI, you must edit this file:

https://github.com/ory/kratos/blob/master/cmd/clidoc/main.go

The cmd/clidoc/main.go is the general path for all Ory projects.

The command to generate the CLI docs can be found here:
https://github.com/ory/x/blob/master/clidoc/generate.go#L96