Choose an identity's data region

On Ory Network's Global Region, you can choose where each identity's personal data is stored by setting its region. For example, create an identity in Europe or move an existing identity from the US to Europe when a customer's residency requirements change.

The region is a top-level identity field, alongside schema_id and traits. It is specific to Ory Network and doesn't belong in your identity schema.

See Personal data location and homing for more about project storage locations.

Create an identity in a region

Use your Global Region project's endpoint and a project API key. The examples assume an identity schema named default with an email trait; adjust these to match your project.

export ORY_PROJECT_URL="https://YOUR_PROJECT_SLUG.projects.oryapis.com"
export ORY_API_KEY="YOUR_PROJECT_API_KEY"

Send region in the create identity request:

curl --request POST "${ORY_PROJECT_URL}/admin/identities" \
  --header "Authorization: Bearer ${ORY_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "schema_id": "default",
    "traits": { "email": "[email protected]" },
    "region": "eu-central"
  }'

The response includes the identity's id and region. If you omit region, Ory uses the project's default homing behavior within its home_region.

Read or move an identity

Set IDENTITY_ID to the ID returned when you created the identity. Read its current region with GET /admin/identities/{id}:

export IDENTITY_ID="YOUR_IDENTITY_ID"

curl "${ORY_PROJECT_URL}/admin/identities/${IDENTITY_ID}" \
  --header "Authorization: Bearer ${ORY_API_KEY}"

To move the identity to US west, send a JSON Patch on /region:

curl --request PATCH "${ORY_PROJECT_URL}/admin/identities/${IDENTITY_ID}" \
  --header "Authorization: Bearer ${ORY_API_KEY}" \
  --header "Content-Type: application/json-patch+json" \
  --data '[{"op": "replace", "path": "/region", "value": "us-west"}]'

Both add and replace are supported on /region. Other operations, including remove, return 400 Bad Request.

The move is synchronous. A 200 OK response guarantees that the physical migration has completed.

The identity search engine uses a separate data store. Its copy of the identity data also moves to the new region, but there is no fixed delay guarantee; search results can lag behind a successful move. Use the identity API for authoritative reads.

Self-service responses expose region as read-only: look for identity.region in /sessions/whoami and wherever an identity object is embedded in a flow response. End users can't change their region through self-service flows.

Set regions during bulk import

For batch imports, set region inside each create object. This example imports one identity in Europe and another in US west:

curl --request PATCH "${ORY_PROJECT_URL}/admin/identities" \
  --header "Authorization: Bearer ${ORY_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "identities": [
      {
        "create": {
          "schema_id": "default",
          "traits": { "email": "[email protected]" },
          "region": "eu-central"
        }
      },
      {
        "create": {
          "schema_id": "default",
          "traits": { "email": "[email protected]" },
          "region": "us-west"
        }
      }
    ]
  }'

See Import identities to include credentials and handle per-identity import results.

Set a region for SSO provisioning

SCIM, SAML, and OIDC provisioning can select a region through a Jsonnet mapper or an organization's default_region:

1. An explicit identity.region in the mapper output takes precedence.
2. If the mapper omits the region, Ory uses the organization's default_region.
3. If neither is set, Ory uses the request's gateway region, constrained by the project's home_region.

For example, add 'default_region' to an organization's configuration and set it to "eu-central" for newly provisioned identities in Europe:

{
  "default_region": "eu-central"
}

Apply it using the organization management instructions, preserving the organization's other fields. This default controls provisioning; use the identity PATCH request above to move an existing identity.

To select a region in a mapper, add region alongside traits in its identity output. For example, this SCIM mapper provisions identities in US east:

local scim = std.extVar('scim');

{
  identity: {
    traits: {
      email: scim.userName,
    },
    region: 'us-east',
  },
}

SAML and OIDC mappers use the same identity.region output field. Both mapper regions and organization defaults must be within the project's home_region.