Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

API references

Identity Store API references

search

Please Note:

Identity Store API references

The OneWelcome Identity Platform provides the Identity Store (IDS) service. The Identity Store is a multi-tenant identity repository that stores and manages user identities and their attributes. It supports a flexible, schema-driven data model with attribute projection, filtering, and sorting, as well as per-attribute metadata through the Attribute Value Metadata (AVM) mechanism.

Identity Store APIs

The Identity Store service includes the following APIs:

  • Identity Management API: Provides endpoints for the following tasks:

    • List identities: Retrieve a paginated list of identities with optional filtering, sorting, and attribute projection.

    • Find by identifier: Look up a single identity by an exact match on an identifier attribute.

    • Get identity: Retrieve a single identity by its unique ID.

    • Create identity: Create a new identity that conforms to the tenant identity schema.

    • Replace identity: Fully replace an existing identity (PUT).

    • Update identity: Partially update one or more attribute values using JSON Patch operations (PATCH).

    • Soft delete: Mark an identity as deleted without permanently removing it.

    • Hard delete: Permanently remove an identity record.

  • Data Model API: Provides endpoints for the following tasks:

    • Get data model: Retrieve the full attribute schema (Attribute Schema Metadata) for all resource types or a specific resource type.

    • Update data model: Create or update custom attribute definitions for a resource type (bulk upsert).

    • Delete attributes: Permanently remove custom attribute definitions from the data model.

  • Attribute Value Metadata (AVM) API: Provides endpoints for the following tasks:

    • Get AVM entries: Retrieve all attribute value metadata entries for a given identity.

    • Upsert AVM entries: Create or update metadata entries for specific attributes of an identity.

    • Replace AVM entries: Replace all AVM entries for an identity.

    • Delete AVM entries: Remove AVM entries for specific attributes.

  • Canonical attributes API: Read the primary email and primary phone number of an identity. See Canonical attributes.

Canonical attributes

Canonical attributes are system-managed attributes that uniquely identify records across systems. The tenant's emails and phoneNumbers attributes are canonical. The platform provisions them automatically, so API consumers cannot create or delete them.

  • Read-only primary endpoints: GET /api/v1/identities/{id}/emails/primary and GET /api/v1/identities/{id}/phoneNumbers/primary return the entry marked primary: true. Both endpoints return the following errors:

    Status Error code Meaning
    404 IDENTITY_NOT_FOUND or RESOURCE_NOT_FOUND The identity does not exist, or the identity has no entry marked primary: true.
    412 CANONICAL_ATTRIBUTE_NOT_PROVISIONED The canonical schema (emails or phoneNumbers) is not provisioned for the tenant.

  • Managing collections: Add, update, and remove emails and phone numbers through the identity update API. No canonical write endpoints exist.

  • Canonical filters on the data model: GET /api/v1/config/data-model/ and GET /api/v1/config/data-model/{resourceType} accept two optional query parameters:

    Parameter Returns
    canonical=true Attributes where isCanonical is true.
    identifier=true Attributes where the isIdentifier attribute schema metadata is true.

    If both parameters are specified, the response returns the union of the matching attributes. For complex attributes, only the matching sub-attributes are returned.

Authentication

All Identity Store API endpoints require OAuth2 Bearer tokens. The following scopes and roles control access:

Scope / Role Description
ids_api_read Read-only access to identities.
ids_api_write Write access to create and update identities.
ids_api_user User-level access to read and write identities and AVM entries.
ids_api_admin Full administrative access to all Identity Store APIs.
ids_api_config Access to read and manage the data model configuration.
ids_api_delete Permission to permanently delete identities (hard delete).
identity:identities:emails:read Read the primary email of an identity (S2S/M2M client).
identity:identities:phoneNumbers:read Read the primary phone number of an identity (S2S/M2M client).
identity_store_read (role) Admin user role for read-only access.
identity_store_write (role) Admin user role for read and write access.

The following table lists the scopes each operation accepts. A token needs at least one of the listed scopes.

Operation Scopes (any of)
Identity GET (single, list, by identifier) ids_api_admin, ids_api_read, ids_api_user
Identity create, PUT, PATCH, soft delete ids_api_admin, ids_api_write, ids_api_user
Hard delete ids_api_admin, ids_api_delete, ids_api_user. A token without ids_api_admin can only hard delete its own identity.
AVM, all operations ids_api_admin, ids_api_user
Data model, all operations ids_api_admin, ids_api_config
Primary email identity:identities:emails:read
Primary phone number identity:identities:phoneNumbers:read

On this page