Skip to main content

Manage identity schemas

This document explains how to create, update, and manage identity schemas in Ory Network.

Use an existing preset

Ory Network provides four basic preset schemas that are ready to use out of the box. If you are just getting started with Ory Network, use one of the presets to make your life easier.

  1. Go to Identities > Identity Schema in the Ory Console.
  2. From the Active schema drop down, select the schema you want to use.
  3. Click the Change active schema button to apply the schema to your project.

Active schema dropdown

caution

Be aware that changing the active schema will affect all new identities created in the project. Existing identities might not be able to sign in, for example if you change from an email based schema, to a username based schema.

Create custom schema

If the presets do not fit your needs, you can create a custom schema. Follow these steps to create a custom schema:

  1. Go to Identities > Identity Schema in the Ory Console.
  2. From the Select template drop down, select the schema you want to use as a template.
  3. Click the Duplicate to make changes button.
  4. Give your schema a name.
  5. Customize the schema to your needs. Read more about the customization options.
  6. Click the Save button to save.
  7. Confirm the changes by clicking the Confirm button in the confirmation dialog.

Create a new schema

To make this schema the active schema for your project, select the newly created schema from the Active schema dropdown and click the Change active schema button.

Update identity schemas

Identity schemas are immutable to prevent inconsistencies in the data. This means, that you cannot update an existing schema. However, you can use the existing schema as a template to create a new schema. Simply follow the steps in Creating custom schemas and select the current schema as a template.

It's recommended to manage identity schemas in version control. Learn more about managing Ory Network configuration in git.

Update identities to use a new schema

Updating the identity schema of a project can result in inconsistencies between the new schema and the identities created with the old schema. Follow these steps to patch identities after updating the identity schema. If you are self-hosting Ory, you can follow the same steps by using the API or Ory Kratos CLI.

The following steps are for updating one identity. If you have more identities that should be patched to the new schema, repeat the steps 4 to 7 or check out the example code for bulk updating identities below.

  1. Retrieve the Project ID.

    ory list projects

    export PROJECT_ID={project-id}
  2. Create a new identity with the updated schema - through the registration interface or Ory Console and copy the schema_id of the identity you just created.

    Identity schema ID and URL

  3. Get all identities of the project using the following command:

    ory list identities --project "$PROJECT_ID" --format json-pretty
  4. Find the identity to be updated and note down their id.

  5. To update the identity, you need to use the Admin API. The API requires the Ory Network Project slug, API Key, and identity ID. Set them as environment variables:

    export ORY_API_KEY={api-key}
    export ORY_SLUG={project-slug}
    export IDENTITY_ID={identity-id}

    Assess the required updates in traits. You need to add, remove, or update existing traits to match the new identity schema. You also need to change the schema_id to the new schema. For instance, adding a new trait and removing an old trait:

Using the patchIdentity API, you can change the identity schema and traits directly.

Using patchIdentity is the recommended way to update identities.

curl --location --request PATCH "https://$ORY_SLUG.projects.oryapis.com/admin/identities/$IDENTITY_ID" \
--header "Authorization: Bearer $ORY_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
{
"op": "replace",
"path": "/schema_id",
"value": "{new-schema-id}"
},
{
"op": "remove",
"path": "/traits/foo"
},
{
"op": "add",
"path": "/traits/bar",
"value": "barfoo"
}
]'

This should return the modified identity as the response.

Now, you have migrated a single identity to a new identity schema. If you have more identities to be patched to the new schema, repeat the above process for each of them.