Identity API (public): schemas

The request and response bodies of the operations in this API.

AcceptInvitationResponseDto

Property	Type	Required	Description
`acceptedAt`	string (date-time)	yes	Timestamp when the invitation was accepted
`invitationId`	string	yes	ID of the invitation that was accepted (the invitationId of the invitation.invitation.accepted event)
`organizationId`	string	yes	Organization ID the user was added to
`organizationName`	string	yes	Organization name
`role`	string	yes	Role assigned to the user
`userId`	string	yes	ID of the person who accepted it (the userId of the invitation.invitation.accepted event)

AddGroupMemberDto

Property	Type	Required	Description
`userId`	string (uuid)	yes	Keycloak user id to add to the group.

AddOrganizationMemberDto

Property	Type	Required	Description
`role`	one of `"org_owner"`, `"org_admin"`, `"org_member"`	no	Role to assign to the user in the organization

ChangeMemberRoleDto

Property	Type	Required	Description
`role`	one of `"org_owner"`, `"org_admin"`, `"org_member"`	yes	New role for the member

CreateGroupDto

Property	Type	Required	Description
`attributes`	map of array of string	no	Free-form Keycloak attributes (string-array values). Consumers tag groups with platform-specific keys (e.g. purpose, region, description).
`name`	string	yes	Group name. Non-empty, at most 255 characters, no "/" (groups are addressed by a slash-delimited path), and not starting with the reserved prefix "user-". The rule is asserted by `assertUsableGroupName` in the service rather than by decorators here, because a group can be created through more than one door and class-validator runs only at the boundary of the door that declares it — a second rule, not a relaxed one.
`parentId`	string	no	Optional parent group id. If omitted the group is created at the top of the realm tree (or scoped to the active organization when one is in context).

CreateInvitationDto

Property	Type	Required	Description
`email`	string (email)	yes	Email address to invite
`role`	one of `"org_owner"`, `"org_admin"`, `"org_member"`	no	Role to assign when invitation is accepted

CreateInvitationRequestDto

Property	Type	Required	Description
`company`	string	no	Company name
`email`	string (email)	yes	Email address
`name`	string	yes	Full name of the requester
`realm`	string	yes	Realm this access request targets. Required: the endpoint is unauthenticated and carries no other tenant signal. Must be a realm this deployment serves; any other value is rejected with 400.

CreateInvitationResponseDto

Property	Type	Required	Description
`code`	string	yes	Invitation code for accepting. Returned only by the call that created the invitation; it cannot be read again.
`createdAt`	string (date-time)	yes	Invitation creation date
`deliveryAttemptedAt`	string (date-time) or null	yes	When the last delivery was attempted. Null when none was.
`deliveryOutcome`	InvitationDeliveryOutcome or null	yes	How the last delivery of this invitation by mail ended. Null when none was attempted.
`email`	string	yes	Invited email address
`expiresAt`	string (date-time)	yes	Invitation expiration date
`id`	string	yes	Invitation ID
`invitedByName`	string	yes	Name of user who sent the invitation
`organizationId`	string	yes	Organization ID
`organizationName`	string	yes	Organization name
`role`	string	yes	Role to be assigned on acceptance
`status`	one of `"PENDING"`, `"ACCEPTED"`, `"EXPIRED"`, `"REVOKED"`	yes	Invitation status

CreateOrganizationDto

Property	Type	Required	Description
`displayName`	string	yes	Organization display name
`domain`	string	no	Organization domain
`metadata`	object	no	Organization metadata
`name`	string	yes	Organization name (slug)

DashboardPreferencesDto

Property	Type	Required	Description
`defaultView`	string	no	Default view field.
`favoriteSymbols`	array of string	no	Favorite symbols field.
`widgetLayout`	object	no	Widget layout field.

DeliverInvitationDto

Property	Type	Required	Description
`applicationId`	string	yes	The registered application whose declared accept URI the link is built on. It must declare an invitation accept URI.
`locale`	string	no	The language of the mail, when the realm declares wording for it. Absent means the realm default.

DeliverInvitationResponseDto

Property	Type	Required	Description
`acceptUrl`	string	yes	The link the invitee follows: the application's declared accept URI with a fresh `code`. Returned only by this call; it cannot be read again.
`delivery`	InvitationDeliveryDto	yes

GroupResponseDto

Property	Type	Required	Description
`attributes`	map of array of string	yes	Free-form Keycloak attributes (string-array values). Consumer-defined keys only — the identity service's internal bookkeeping keys (e.g. ownership and per-member role attributes) are stripped from this surface.
`childGroupIds`	array of string	yes	Direct child group ids (one level deep).
`id`	string	yes	Group ID (Keycloak UUID).
`name`	string	yes	Group name.
`parentId`	string or null	yes	Direct parent group id, or null when the group sits at the realm root.
`path`	string	yes	Full Keycloak path (e.g. "/acme/security-champions").
`rootGroupId`	string	yes	Top-level ancestor id of this group. In platforms that use the top-level group as the org boundary, this is the organization id. Equals `id` for top-level groups.

InvitationDeliveryDto

Property	Type	Required	Description
`attemptedAt`	string (date-time)	yes	When the attempt was made.
`outcome`	InvitationDeliveryOutcome	yes	How the attempt ended. A failed or unknown delivery never cancels the invitation.
`reason`	InvitationDeliveryReason	no	Why the mail was not sent, when it was not. A closed vocabulary; never carries the link.

InvitationDeliveryOutcome

How the last delivery of this invitation by mail ended. Null when none was attempted.

Type: one of "SENT", "FAILED", "UNKNOWN", "NOT_CONFIGURED"

InvitationDeliveryReason

Why the mail was not sent, when it was not. A closed vocabulary; never carries the link.

Type: string (11 values)

InvitationRequestResponseDto

Property	Type	Required	Description
`company`	string or null	no	Company name
`createdAt`	string (date-time)	yes	When the request was created
`email`	string	yes	Requester email
`id`	string	yes	Invitation request ID
`name`	string	yes	Requester name
`status`	one of `"PENDING"`, `"APPROVED"`, `"REJECTED"`	yes	Request status

InvitationResponseDto

Property	Type	Required	Description
`createdAt`	string (date-time)	yes	Invitation creation date
`deliveryAttemptedAt`	string (date-time) or null	yes	When the last delivery was attempted. Null when none was.
`deliveryOutcome`	InvitationDeliveryOutcome or null	yes	How the last delivery of this invitation by mail ended. Null when none was attempted.
`email`	string	yes	Invited email address
`expiresAt`	string (date-time)	yes	Invitation expiration date
`id`	string	yes	Invitation ID
`invitedByName`	string	yes	Name of user who sent the invitation
`organizationId`	string	yes	Organization ID
`organizationName`	string	yes	Organization name
`role`	string	yes	Role to be assigned on acceptance
`status`	one of `"PENDING"`, `"ACCEPTED"`, `"EXPIRED"`, `"REVOKED"`	yes	Invitation status

IssueScimCredentialDto

Property	Type	Required	Description
`label`	string	yes	What the credential is for, shown to administrators (for example the identity provider it is configured in).

IssuedScimCredentialDto

Property	Type	Required	Description
`createdAt`	string (date-time)	yes
`createdBy`	string	yes	Principal id of the administrator who issued it.
`expiresAt`	string (date-time) or null	no	When a RETIRING credential stops being accepted.
`id`	string	yes
`label`	string	yes
`organizationId`	string	yes
`prefix`	string	yes	The public start of the token, to tell credentials apart.
`revokedAt`	string (date-time) or null	no
`revokedBy`	string or null	no	Principal id of the administrator who revoked it; null when the service revoked it.
`revokedReason`	ScimCredentialRevocationReason or null	no
`rotatedFrom`	string or null	no	The credential this one replaced, when issued by a rotation.
`state`	ScimCredentialState	yes
`token`	string	yes	The bearer token for the identity provider. Returned only by this call; it cannot be read again.
`updatedAt`	string (date-time)	yes

NotificationPreferencesDto

Property	Type	Required	Description
`alertSeverities`	array of string	no	Alert severities field.
`digestFrequency`	one of `"realtime"`, `"hourly"`, `"daily"`, `"weekly"`	no	Digest frequency field.
`email`	boolean	no	Email field.
`push`	boolean	no	Push field.

OrganizationDirectoryEntryDto

Property	Type	Required	Description
`displayName`	string	yes	Human-readable name to show in a picker. Falls back to the email local part when the user has no name set, so it is never empty.
`email`	string	yes	User email. Served to every reader of the directory because it is the disambiguator between two members with the same display name.
`firstName`	string	no	First name. Served only to a reader with organization-administrator authority.
`id`	string	yes	User ID
`joinedAt`	string (date-time)	no	When the user joined the organization. Served only to a reader with organization-administrator authority.
`lastName`	string	no	Last name. Served only to a reader with organization-administrator authority.
`role`	one of `"org_owner"`, `"org_admin"`, `"org_member"`	no	Role in the organization. Served only to a reader with organization-administrator authority.

OrganizationResponseDto

Property	Type	Required	Description
`createdAt`	string (date-time) or null	no	Organization creation timestamp
`deletionRequestedAt`	string (date-time) or null	yes	When a deletion of this organization was requested, or null. A requested organization is retired — inactive, without members, and refusing changes — and is kept until it is purged.
`displayName`	string	yes	Organization display name
`domain`	string or null	no	Organization domain
`id`	string	yes	Organization ID (Keycloak group ID)
`isActive`	boolean	yes	Whether the organization is active
`isProtected`	boolean	yes	Whether the organization is protected from deletion. A protected organization cannot be deleted through this API by any caller; the delete endpoints answer 409 ORGANIZATION_PROTECTED. Callers that own their own destructive teardown of an organization should read this before acting.
`metadata`	object	yes	Organization metadata
`name`	string	yes	Organization name (slug)
`role`	one of `"org_owner"`, `"org_admin"`, `"org_member"` or null	no	Current user role in the organization when available
`updatedAt`	string (date-time) or null	no	Organization last update timestamp

PlatformRole

Installation roles the user holds natively in this realm; only members of the closed PlatformRole set are ever stated

Type: one of "platform_owner", "platform_admin", "platform_operator"

ProviderLogoutRequestDto

Property	Type	Required	Description
`logout_token`	string	yes	The provider-signed logout token (a JWT).

ScimCredentialDto

Property	Type	Required	Description
`createdAt`	string (date-time)	yes
`createdBy`	string	yes	Principal id of the administrator who issued it.
`expiresAt`	string (date-time) or null	no	When a RETIRING credential stops being accepted.
`id`	string	yes
`label`	string	yes
`organizationId`	string	yes
`prefix`	string	yes	The public start of the token, to tell credentials apart.
`revokedAt`	string (date-time) or null	no
`revokedBy`	string or null	no	Principal id of the administrator who revoked it; null when the service revoked it.
`revokedReason`	ScimCredentialRevocationReason or null	no
`rotatedFrom`	string or null	no	The credential this one replaced, when issued by a rotation.
`state`	ScimCredentialState	yes
`updatedAt`	string (date-time)	yes

ScimCredentialRevocationReason

Type: one of "ADMINISTRATOR_REVOKED", "ORGANIZATION_RETIRED"

ScimCredentialState

Type: one of "ACTIVE", "RETIRING", "REVOKED"

UpdateGroupDto

Property	Type	Required	Description
`attributes`	map of array of string	no	Replacement attribute map. Replaces ALL attributes; merge semantics live in the consumer. Pass `null` for a key to delete it.
`name`	string	no	Updated group name. Same rule as create, asserted in the service by `assertUsableGroupName`.

UpdateMeDto

Property	Type	Required	Description
`firstName`	string	no	First name
`lastName`	string	no	Last name

UpdateOrganizationByOwnerDto

Property	Type	Required	Description
`displayName`	string	no	Organization display name
`metadata`	object	no	Organization metadata (custom key-value data)
`name`	string	no	Organization name (slug)

UpdatePreferencesDto

Property	Type	Required	Description
`dashboard`	DashboardPreferencesDto	no	Dashboard preferences
`locale`	string	no	Locale code
`notifications`	NotificationPreferencesDto	no	Notification preferences
`theme`	one of `"light"`, `"dark"`, `"system"`	no	UI theme
`timezone`	string	no	IANA timezone

UserResponseDto

Property	Type	Required	Description
`createdAt`	string (date-time) or null	no	User creation timestamp
`email`	string	yes	User email address
`firstName`	string or null	no	User first name
`groupIds`	array of string	no	Ids of the groups inside the active organization that the user is a member of. Populated only when an organization context is supplied; an empty array means the user belongs to no group in that organization. The organization group itself is never included — belonging to it is membership of the organization, not of a group inside it.
`id`	string	yes	User ID (Keycloak subject ID)
`isActive`	boolean	yes	Whether the user is active
`lastLoginAt`	string (date-time) or null	no	Last login timestamp
`lastName`	string or null	no	User last name
`orgRole`	string	no	The user's membership role within the active organization context (e.g. owner/admin/member). Populated only when an organization context is supplied; absent when no context is given or the user is not a member.
`platformRoles`	array of PlatformRole	yes	Installation roles the user holds natively in this realm; only members of the closed PlatformRole set are ever stated
`preferences`	object	no	The caller's own preferences, an opaque object this service stores and never interprets. Present on the self profile (GET /users/me and PATCH /users/me/preferences) once the realm's preferences are held here; absent while a realm's one-time import has not run — never an empty object standing in for unknown.
`updatedAt`	string (date-time) or null	no	User last update timestamp