Skip to main content

Create, update, and manage identity schemas

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

Create identity schemas

Follow these steps to create a custom identity schema in Ory Network:

  1. Sign in to Ory Console and select Identity Schema.
  2. Using the dropdown menu, select one of the preset schemas or the empty template as the starting point for your custom schema.
  3. Check the Customize Identity Schema box to enable editing of the schema.
  4. Adjust the schema to your needs. Add, remove, or adjust traits.
  5. Define the name of the custom schema in the Identity Model Schema text box.
  6. Click the Update button to save.

Update identity schemas

To update an identity schema, you must create a new revision of that schema. You can't update existing identity schemas by editing them.

For example, to update an identity schema named "Customer Type 1", follow these steps:

  1. Sign in to Ory Console and select Identity Schema.
  2. Using the dropdown menu, select the "Customer Type 1" schema.
  3. Check the Customize Identity Schema box to enable editing and make the necessary changes.
  4. Enter a new name in the Identity Model Schema text box, for example, "Customer Type 2".
  5. Click the Update button to save.

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.