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.

An exemplary payload for importing an identity with a verified address:

{
  "schema_id": "preset://email",
  "traits": {
    "email": "docs-verify@example.org"
  },
  "verifiable_addresses": [
    {
      "value": "docs-verify@example.org",
      "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": "docs-verify@example.org"
  },
  "verifiable_addresses": [
    {
      "value": "docs-verify@example.org",
      "verified": true,
      "via": "email",
      "status": "completed"
    }
  ]
}' https://playground.projects.oryapis.com/admin/identities

The API then responds with the created identity:

{
  "id": "880052ae-d32c-4b56-b82d-0dc711080910",
  "schema_id": "preset://email",
  "schema_url": "http://localhost:4455/schemas/cHJlc2V0Oi8vZW1haWw",
  "state": "active",
  "state_changed_at": "2022-02-24T15:33:17.845589803Z",
  "traits": {
    "email": "docs-verify@example.org"
  },
  "verifiable_addresses": [
    {
      "id": "c3f67b59-ab58-410b-971a-06b80f38468a",
      "value": "docs-verify@example.org",
      "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": "docs-verify@example.org",
      "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": "docs-cleartext@example.org"
  },
  "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 docs-cleartext@example.org 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": "docs-hash@example.org"
  },
  "credentials": {
    "password": {
      "config": {
        "hashed_password": "$2a$10$ZsCsoVQ3xfBG/K2z2XpBf.tm90GZmtOqtqWcB5.pYd5Eq8y7RlDyq"
      }
    }
  }
}

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": "docs-oidc@example.org"
  },
  "credentials": {
    "oidc": {
      "config": {
        "providers": [
          {
            "provider": "github",
            "subject": "12345"
          },
          {
            "provider": "google",
            "subject": "12345"
          }
        ]
      }
    }
  }
}