Skip to main content

Import identities

Ory allows you to import identities from any other system. To import identities, you use the same endpoint as for creating identities. The main difference between creating and importing identities is that when you import identities, you must provide the credentials field.

Importing verified addresses

Use the verifiable_addresses field to import a verified address like an email address.

danger

You must ensure that address verification is enabled and that the verifiable_address is present in the identity's traits. If the identity traits do not have the address set as the "verified address" type, the imported values will be deleted on the next identity update.

This is a sample payload for importing an identity with a verified address:

{
"schema_id": "preset://email",
"traits": {
"email": "[email protected]"
},
"verifiable_addresses": [
{
"value": "[email protected]",
"verified": true,
"via": "email",
"status": "completed"
}
]
}

Test the above example with a cURL command:

curl --request POST -sL \
--header "Authorization: Bearer ory_pat_xRKLsFEOUFQFVBjd6o3FQDifaLYhabGd" \
--header "Content-Type: application/json" \
--data '{
"schema_id": "preset://email",
"traits": {
"email": "[email protected]"
},
"verifiable_addresses": [
{
"value": "[email protected]",
"verified": true,
"via": "email",
"status": "completed"
}
]
}' https://{your-project-slug}.projects.oryapis.com/admin/identities

The API response contains the created identity:

{
"id": "880052ae-d32c-4b56-b82d-0dc711080910",
"schema_id": "preset://email",
"schema_url": "https://{your-project-slug}.projects.oryapis.com/schemas/cHJlc2V0Oi8vZW1haWw",
"state": "active",
"state_changed_at": "2022-02-24T15:33:17.845589803Z",
"traits": {
"email": "[email protected]"
},
"verifiable_addresses": [
{
"id": "c3f67b59-ab58-410b-971a-06b80f38468a",
"value": "[email protected]",
"verified": true,
"via": "email",
"status": "completed",
"created_at": "2022-02-24T15:33:17.848941Z",
"updated_at": "2022-02-24T15:33:17.848941Z"
}
],
"recovery_addresses": [
{
"id": "819b53bf-79e3-452e-8a9b-0323ec9d193c",
"value": "[email protected]",
"via": "email",
"created_at": "2022-02-24T15:33:17.849758Z",
"updated_at": "2022-02-24T15:33:17.849758Z"
}
],
"created_at": "2022-02-24T15:33:17.848475Z",
"updated_at": "2022-02-24T15:33:17.848475Z"
}

Importing recovery addresses

It is possible to import a list of recovery_addresses - similar to verifiable_addresses. It is better to let the identity schema handle setting the appropriate fields since there is no status to set for this address type.

We don't recommend setting these fields as they will be overwritten by other self-service flows. For more information on account recovery read the account recovery documentation.

Importing credentials

Ory supports importing credentials for identities including passwords and social sign-in connections.

Clear text password

To import a clear text password, provide the password in the JSON payload.

danger

Password imports don't use any password validation. Users have to update their password according to the policy themselves using self-service flows.

{
"schema_id": "preset://email",
"traits": {
"email": "[email protected]"
},
"credentials": {
"password": {
"config": {
"password": "the-password"
}
}
}
}

The password the-password will then be hashed according to the configured password hashing algorithm and stored in the database. The identity will be able to sign in using [email protected] and the-password as credentials.

Hashed passwords

To import a hashed password, provide the hashed password in the JSON payload.

{
"schema_id": "preset://email",
"traits": {
"email": "[email protected]"
},
"credentials": {
"password": {
"config": {
"hashed_password": "$2a$10$ZsCsoVQ3xfBG/K2z2XpBf.tm90GZmtOqtqWcB5.pYd5Eq8y7RlDyq"
}
}
}
}

The value of the hashed password is different depending on the algorithm used. The following algorithms are supported:

Ory Identities can hash passwords by BCrypt and can compare stored BCrypt hash and migrate if configured hasher (hashers.algorithm) isn't BCrypt.

BCrypt format is described here.

Social sign-in connections

When importing social sign-in connections, the provider field is the social sign-in provider ID you set in your social sign-in configuration. The subject ID must be the ID of the user on the given platform. Usually, this is the sub claim of the OpenID Connect ID Token provider such as Google.

{
"schema_id": "preset://email",
"traits": {
"email": "[email protected]"
},
"credentials": {
"oidc": {
"config": {
"providers": [
{
"provider": "github",
"subject": "12345"
},
{
"provider": "google",
"subject": "12345"
}
]
}
}
}
}

Bulk import identities from other providers

To import multiple identities into Ory Identities, use the Identity Import API.

A maximum of 2000 identities can be created in a single request. If you need to import more identities, split the import into multiple requests.

The endpoint accepts a JSON array of identities, each of which must have a create property that holds the identity that should be created. Optionally, you can specify a patch_id property which will be returned in the response. This can be used to correlate the response with the patch.

The following example shows how to import two identities. It will create two identities with the email addresses [email protected] and [email protected] and the passwords foopassword and barpassword respectively.

curl --location --request PATCH 'https://${YOUR_PROJECT_SLUG}.projects.oryapis.com/admin/identities' \
--header 'Authorization: Bearer ${YOUR_ORY_ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
"identities": [
{
"create": {
"credentials": {
"password": {
"config": {
"password": "foopassword"
}
}
},
"state": "active",
"traits": {
"email": "[email protected]"
},
"schema_id": "preset://email"
}
},
{
"create": {
"credentials": {
"password": {
"config": {
"password": "barpassword"
}
}
},
"state": "active",
"traits": {
"email": "[email protected]"
},
"schema_id": "preset://email"
}
}
]
}'

The service will respond with the two identity IDs created:

{
"identities": [
{
"action": "create",
"identity": "55f93ea4-09ff-4273-8b88-082cc70d6d44"
},
{
"action": "create",
"identity": "f70c9b29-4790-4330-90dc-920db16a4b85"
}
]
}