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:

Ory Console

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.

Ory CLI

# Encode your schema to Base64 and export it to a variable.
schema=$(cat {path-to-json-with-identity-schema} | base64)

# Update your project's configuration.
ory patch identity-config {your-project-id} \
  --replace '/identity/default_schema_id="{unique-schema-id}"' \
  --replace '/identity/schemas=[{"id":"{unique-schema-id}","url":"base64://'$schema'"}]'

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.

   

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:

cURL and patchIdentity

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.

Ory SDK

note

This example uses the Ory Go SDK. If you wish to use a different programming language for identity schema migration, you can apply the same logic using the Ory SDK for your programming language. Ory can also provide example code in your preferred language. Please contact support@ory.sh.

package main

import (
    "context"
    "fmt"

    client "github.com/ory/client-go"
)

const (
    YOUR_ORY_API_KEY        = "{your-api-key}"
    YOUR_ORY_PROJECT_SLUG   = "{your-project-slug}"
    OLD_SCHEMA_ID           = "{old-schema-id}" // The schema ID of the identity to be updated, it is recommended to set this explicitly to avoid updating an identity with a different schema.
    UPDATE_TO_NEW_SCHEMA_ID = "{new-schema-id}"
    IDENTITY_ID_TO_UPDATE   = "{identity-id}"
)

func main() {
    if err := migrateSchema(UPDATE_TO_NEW_SCHEMA_ID, IDENTITY_ID_TO_UPDATE); err != nil {
        panic(err)
    }
}

func migrateSchema(toSchema, identityID string) error {
    // Initialize the client configuration
    cfg := client.NewConfiguration()
    cfg.Servers = client.ServerConfigurations{
        {
            URL: fmt.Sprintf("https://%s.projects.oryapis.com", YOUR_ORY_PROJECT_SLUG),
        },
    }

    // Create an instance of the API client
    ory := client.NewAPIClient(cfg)

    // Set the access token
    ctx := context.Background()
    ctx = context.WithValue(ctx, client.ContextAccessToken, YOUR_ORY_API_KEY)

    // Check if the new schema exists
    _, _, err := ory.IdentityApi.GetIdentitySchema(ctx, toSchema).Execute()
    if err != nil {
        return err
    }

    // Check if the identity exists
    identity, _, err := ory.IdentityApi.GetIdentity(ctx, identityID).Execute()
    if err != nil {
        return err
    }
    if identity.SchemaId == toSchema {
        fmt.Println("already migrated, no update required")
        return nil
    }

    // Check if the identity's schema ID matches the old schema ID
    if identity.SchemaId != OLD_SCHEMA_ID {
        return fmt.Errorf("identity's schema ID does not match the old schema ID")
    }

    // Prepare the JSON patch for the update
    jsonPatch := []client.JsonPatch{
        {Op: "replace", Path: "/schema_id", Value: toSchema},
    }

    // Apply the JSON patch to update the identity
    _, _, err = ory.IdentityApi.PatchIdentity(ctx, identityID).JsonPatch(jsonPatch).Execute()
    if err != nil {
        return err
    }

    // Verify that the schema was updated
    updatedIdentity, _, err := ory.IdentityApi.GetIdentity(ctx, identityID).Execute()
    if err != nil {
        return err
    }

    if updatedIdentity.SchemaId != toSchema {
        return fmt.Errorf("schema wasn't updated")
    }

    fmt.Println("Identity schema updated 🎉")

    return nil
}

cURL and updateIdentity

Update the identity using the updateIdentity API:

1. Save the existing identity

   export IDENTITY_ID={IDENTITY_ID}
   ory get identity "$IDENTITY_ID" --project "$PROJECT_ID" --format json-pretty > identity-"$IDENTITY_ID".json

2. Update the saved JSON to match the new identity schema

   -"schema_id" : "{old-schema-id}",
   +"schema_id" : "{new-schema-id}",
   "traits": {
   -"foo": "foobar"
   +"bar": barfoo
   }

3. Update the identity using PUT

   curl -d "@identity-$IDENTITY_ID.json" -X PUT https://$ORY_SLUG.projects.oryapis.com/admin/identities/$IDENTITY_ID \
   -H "Authorization: Bearer $ORY_API_KEY" \
   -H'Content-Type: application/json'

info

The updateIdentity API overwrites the existing identity with the one provided in the request body. Omit any fields that should not be changed, including the credentials field.

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.