Create and Invite Identities

This document walks you through the administrative identity management in Ory. You should already be familiar with the Identity Schema before reading this guide.

There are three principal flows supported for creating identities as an administrator:

1. Create users.
2. Invite users - e.g. inviting a new employee to your organization IT.
3. Importing existing users - e.g. when migrating from another system to Ory Kratos.

Create an Identity

The goal of this flow is to create an identity and provide the end-user with a way of signing into the identity and setting their password (or any other type of credential) for future logins. To achieve this, first create the identity and set its traits and schema:

Ory Cloud

curl --request POST -sL \\
  --header "Authorization: Bearer ory_pat_xRKLsFEOUFQFVBjd6o3FQDifaLYhabGd" \\
  --header "Content-Type: application/json" \\
  --data '{
  "schema_id": "preset://email",
  "traits": {
    "email": "docs@example.org"
  }
}' https://playground.projects.oryapis.com/admin/identities

Self-Hosted Ory Kratos

Run Ory Kratos easily on your local machine or server with the Ory Cloud Hosted UI and default configuration in Docker:

git clone --depth 1 --branch master https://github.com/ory/kratos.git
cd kratos
git checkout master
git pull -ff
docker-compose -f quickstart.yml \
  -f contrib/quickstart/kratos/cloud/quickstart.yml up

Ory Kratos will then be avaiable at 127.0.0.1:4433 (public port) and 127.0.0.1:4434 (admin port).

And use it to create an identity:

curl --request POST -sL \\
  --header "Content-Type: application/json" \\
  --data '{
  "schema_id": "preset://email",
  "traits": {
    "email": "docs@example.org"
  }
}' http://127.0.0.1:4434/identities

The server responds with something similar to:

{
  "id": "e01b5f2f-6afc-4194-8578-4cebcf69a4d5",
  "schema_id": "preset://email",
  "schema_url": "https://playground.projects.oryapis.com/api/kratos/public/schemas/cHJlc2V0Oi8vZW1haWw",
  "state": "active",
  "state_changed_at": "2022-02-24T13:38:05.27510048Z",
  "traits": {
    "email": "docs@example.org"
  },
  "verifiable_addresses": [
    {
      "id": "c6cea2a7-f419-42fe-a610-456bea02aab5",
      "value": "docs@example.org",
      "verified": false,
      "via": "email",
      "status": "pending",
      "created_at": "2022-02-24T13:38:05.28581Z",
      "updated_at": "2022-02-24T13:38:05.28581Z"
    }
  ],
  "recovery_addresses": [
    {
      "id": "21ff90e1-a9a9-491e-8194-774172420989",
      "value": "docs@example.org",
      "via": "email",
      "created_at": "2022-02-24T13:38:05.29565Z",
      "updated_at": "2022-02-24T13:38:05.29565Z"
    }
  ],
  "created_at": "2022-02-24T13:38:05.27892Z",
  "updated_at": "2022-02-24T13:38:05.27892Z"
}

Keep in mind that you can change the schema_id to reflect the schema you want to use for this identity. Similarly, the trait key/values depend on your schema as well. The command shown does not create a password for the identity or any other type of credential.

Invite Identity

While there is no feature called "user invite", you can initiate account recovery as an administrator which is quite similar to a user invite feature as it allows the user to set their password (or any other credential) and sign in without further intervention.

Please head over to Administrative Account Recovery to learn more.