Identity metadata & traits

Identities have traits and metadata:

• Traits are the attributes of an identity, that can be updated by the identity owner, for example the username or email address.
• Metadata are the attributes defined by the system admin that can't be updated or modified by the identity owner. The only way to update the metadata is to use the /admin/identities APIs. These fields can be used to store, for example, the user's roles, subscription status, etc.

Metadata

There are two types of identity metadata:

• Public: Attributes which can only be modified using the /admin/identities APIs. They are visible to the user when calling toSession() or /sessions/whoami.
• Admin: Attributes which can only be modified and read using the /admin/identities APIs. They are never directly exposed to the identity/user.

note

Metadata is not validated using the identity's JSON schema. You must ensure that the metadata you store is valid according to your schema and you must keep the schema up to date to accommodate changes in the data.

To manage metadata, use the following APIs:

• POST /admin/identities
• GET /admin/identities
• GET /admin/identities/{id}
• PUT /admin/identities/{id}

info

You need an API Key to call these endpoints. Read Authorization with API Keys to learn more.

Traits

Traits are the data associated with an identity. This data can be modified by the identity owner, for example at sign up or in the profile update process. Identity traits can also be modified by users with Ory Identities (Kratos) Admin API access.

note

Ory Identities (Kratos) uses JSON Schema to validate Identity traits.

Each identity can, theoretically, have a different JSON Schema. This can be useful in the following situations:

• There is more than one type of identity in the system for example: customers, support, staff.
• The system includes both human users and "robots" (sometimes also known as named service accounts).
• The system needs to ingest another company's Identity Schema.
• The system's Identity Schema changes or grows over time and requires versioning.

This example illustrates a usage scenario with three types of identities: regular customers, grandfather accounts, and service accounts (for example a Microsoft Service Account). Each identity has one JSON schema that defines it:

• Customers: http://mydomain.com/schemas/v2/customer.schema.json
• Grandfather Accounts: http://mydomain.com/schemas/v1/customer.schema.json
• Service Accounts: http://mydomain.com/schemas/service-account.schema.json

Ory Identities expects the JSON Schemas in its configuration file:

identity:
  # This will be the default JSON Schema. If `schema_id` is empty when creating an identity using the
  # Admin API or a user signs up using a selfservice flow, this schema will be used.
  #
  # This is a required configuration field!
  default_schema_id: person

  # Optionally define additional schemas here:
  schemas:
    # When creating an identity that uses this schema, `traits_schema_id: customer` are set for that identity.
    - id: customer
      url: http://foo.bar.com/customer.schema.json
    - id: person
      url: http://foo.bar.com/person.schema.json

Ory validates the identity traits against the corresponding schema on all "write" operations (create/update). The employed business logic must be able to distinguish these three types of identities. You might use a switch statement like in the following example:

// This is an example program that can deal with all three types of identities
session, err := ory.SessionFromRequest(r)
// some error handling
switch (session.Identity.SchemaID) {
    case "customer":
        // ...
    case "employee":
        // ...
    case "default":
        fallthrough
    default:
        // ...
}