Events API

Authway has events for many of the things that happens in the service. You can tap into these events and write your own logic by registering a webhook or by using our Event API. Note that webhook feature is only available in the Enterprise edition of the service.

Common Properties in all events

Each event payload also contains properties unique to the event. You can find the unique properties in the individual event documentation.

Name Type Description
AggregateId UUID The unique identifier of the aggregate (information entity) that the event happended for.
OwnerId UUID The unique identifier of the owner (tenant) that the event belongs to.
EventId UUID The unique identifier for the event. Can be used for idempotency, logging and more.
Occured DateTime The date and time (in UTC) when the event occurred.
CausedByPersonId UUID The unique identifier of the user that caused the event (if any).
CausedBy string The name of the user that caused the event (if any).
TraceId string The trace id that can be used to trace different actions that is going on in a system.

IpAddressLocation Properties

Depending on environment and configuration some events will include location information based on the IP address. Sources for this information can also be different when hosting your-self compared to Authway IDaaS.

Name Type Description
CountryCode string The two-letter country code (3166-1) representing the country.
Country string The name of the country.
Region string The name of the region.
City string The name of the city.
Latitude decimal The latitude.
Longitude decimal The longitude.

When an IpAddressLocaiton exist in the event, we garuantee that the CountryCode and Country is set, but the other properties will depend on information availability in the source.

Available Events

Organisation Events

To retrieve all organisation events you use the topic “organisation”.

Person Events

To retrieve all organisation events you use the topic “person”.

User Events

To retrieve all organisation events you use the topic “user”.

Organisation module Events

To retrieve all organisation module events you use the topic “organisationmodule”.

Module Events

To retrieve all module events you use the topic “module”.

Subsections of Events API

Subsections of Organisation Events

OrganisationClaimAdded

An organisation got an organisation claim added. To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.organisationclaimadded”.

Name Type Description
AggregateId UUID The unique identifier of the organisation.
ClaimType string The type of claim.
ClaimValue string The claim value.

OrganisationClaimRemoved

An organisation got an organisation claim removed. To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.organisationclaimremoved”.

Name Type Description
AggregateId UUID The unique identifier of the organisation.
ClaimType string The type of claim.
ClaimValue string The claim value.

OrganisationCreated

An organisation is created. It is a new tenant if the ParendId does not have any value (and GroupMotherId and AggregateId is equal). To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.organisationcreated”.

Name Type Description
AggregateId UUID The unique identifier of the organisation.
GroupMotherId UUID The id of the group mother (root organisation) in the organisation tree. For the group mother, this value will be the same as Id.
ParentId UUID The identity of this tenants parent, if any.
Name string The name of the organisation
IdentityNumber string The identity number for the organisation.

TrustedDomainRemoved

An organisation got a trusted domain removed. To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.trusteddomainremoved”.

Name Type Description
AggregateId UUID The unique identifier of the organisation.
Domain string The domain that was removed.

TrustedDomainAdded

An organisation got a trusted domain added. To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.trusteddomainadded”.

Name Type Description
AggregateId UUID The unique identifier of the organisation.
Domain string The domain that was added.

OrganisationUpdated

An organisation is updated. To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.organisationupdated”.

Name Type Description
AggregateId UUID The unique identifier of the organisation.
Name string The name of the organisation
IdentityNumber string The identity number for the organisation.

OrganisationDeleted

An organisation is deleted. To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.organisationdeleted”.

Name Type Description
AggregateId UUID The unique identifier of the organisation.

Subsections of Person Events

PersonCreated

A person is created. It is common for UserCreated to be created at the same time, but it is possible to create a person who are not a user. To retrieve only this event you use the topic “person/irm.aspnetcore.identity.events.personcreated”.

Name Type Description
AggregateId UUID The unique identifier of the person.
OrganisationId UUID The id of the organisation that the person is added to.
FirstName string The first (given) name of the person.
LastName string The last (family) name of the person.
Email string The email for the person. This can be a different email than the username and/or user email.

PersonDeleted

A person is deleted. When a person is deleted, so is all user and person events for that person. The metadata is preserved, but no payload data will be available again. To retrieve only this event you use the topic “person/irm.aspnetcore.identity.events.persondeleted”.

Name Type Description
AggregateId UUID The unique identifier of the person.

PersonUpdated

A person is updated. To retrieve only this event you use the topic “person/irm.aspnetcore.identity.events.personupdated”.

Name Type Description
AggregateId UUID The unique identifier of the person.
OrganisationId UUID The id of the organisation that the person belongs to.
FirstName string The first (given) name of the person.
LastName string The last (family) name of the person.
Email string The email for the person. This can be a different email than the username and/or user email.

Subsections of User Events

UserCreated

A user is created. This can happen multiple times for the same user id, since it is possible to delete only the user and then re-create the user. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.usercreated”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
Username string The username which is unique within the tenant, but can exists for multiple tenants.
Email string The email address of the user. This is typically the same as Username, but the service can be configured to use PhoneNumber or any username and in thoose cases it can differ.
EmailConfirmed bool True if the email is confirmed; otherwise false.
PhoneNumber string The phone number of the user. In a default configuration phone number is not visible and collected, so it is common for this to be null.
PhoneNumberConfirmed string True if the phone number is confirmed; otherwise false.
ValidFrom DateTime The date and time (in UTC) when the user is valid (aka the earliest point in time when the user is allowed to sign-in).
ValidTo DateTime The date and time (in UTC) when the user is valid (aka the latest point in time when the user is allowed to sign-in). Commonly null.
IsSystemUser bool True if this user represents a system (aka an external system); otherwise false.
SendInvitation bool True if an invitation will be send to the user; otherwise false.
AdditionalInvitationParameters string Additional parameters that should be added to the invitation link. Typically it can contain for example a client id to brand the create account page for a specific client.
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserActivated

A user account have been activated, which can be immediately or at Valid from. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.useractivated”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).

Note that there can be a delay until the event is pushed, but it will always be pushed in correct order.

UserUpdated

A user is updated. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userupdated”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
Username string Obsolete.Use UserUsernameChanged event to handle changes of the username instead.
Email string The email address of the user. This is typically the same as Username, but the service can be configured to use PhoneNumber or any username and in thoose cases it can differ.
EmailConfirmed bool True if the email is confirmed; otherwise false.
PhoneNumber string The phone number of the user. In a default configuration phone number is not visible and collected, so it is common for this to be null.
PhoneNumberConfirmed string True if the phone number is confirmed; otherwise false.
ValidFrom DateTime The date and time (in UTC) when the user is valid (aka the earliest point in time when the user is allowed to sign-in).
ValidTo DateTime The date and time (in UTC) when the user is valid (aka the latest point in time when the user is allowed to sign-in). Commonly null.
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserUsernameChanged

The username of a user is changed. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userusernamechanged”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
Username string The username which is unique within the tenant, but can exists for multiple tenants.
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserDeleted

A user is deleted. The user can be deleted, without deleting the person, which also results in that it is possible to re-create the user with the same id. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userdeleted”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).

UserDeviceAdded

An user signed in from a new device. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userdeviceadded”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
DeviceId string The unique identifier of the device.
FromIpAddress string The IP Address of the user that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.

UserDeviceCountryAdded

An user signed in from a known device, but a new country. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userdevicecountryadded”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
DeviceId string The unique identifier of the device.
FromIpAddress string The IP Address of the user that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.

UserInvited

A user is invited to create an account. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userinvited”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserLoginAdded

An user added an external login to the account. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userloginadded”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
LoginProvider string The login provider added.
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserLoginRemoved

An user removed an external login from the account. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userloginremoved”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
LoginProvider string The login provider removed.
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserPasswordAdded

An user added a password. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userpasswordadded”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserPasswordChanged

An user changed the password. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userpasswordchanged”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserPasswordRemoved

An user removed the password from the account. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userpasswordremoved”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserRoleAdded

A user is added to a role. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userroleadded”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
NormalizedRoleName string The unique and normalized role name that the user was added to.
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserRoleRemoved

A user is removed from a role. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userroleremoved”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
NormalizedRoleName string The unique and normalized role name that the user was removed from.
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserSignInAssociated

A user has associated a sign-in from an invitation to create an account. This also means that the email address is confirmed. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.usersigninassociated”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
AuthenticationMethod string The type of authentication that the user used when associating an authentication method.
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserSignedIn

A user signed in. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.usersignedin”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
Kind int Indicates what kind of situation that caused the event. Can be one of these values: 0. Interactive sign-in where user is fully aware; 1. Automatic sign-in where the user is signed-in automatically by single-sign-on; 2. Refresh where an application uses a refresh token to re-new the user sign-in; 3. Impersonate which is when another user impersonates the user.
AuthenticationRequirement string The requirment of the authentication process for the user, for example “1FA” or “2FA”. This will only be set when Kind is 0 or 3.
AuthenticationMethod string The type of authentication that the user used when signing in. This will only be set when Kind os 0 or 3.
FromIpAddress string The IP Address of the user (or service) that caused the event. When kind is 2 (Refresh) this will be the IP Address of the server, not the user, since it is performed over a backchannel.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event. Will be the user’s web browser user agent for all Kind except when Kind = 2 (Refresh) which happens in a backchannel.
Metadata dynamic A dynamic object with additional data for the event.

More about Metadata

Metadata is a dynamic object that can contain different extra properties that might vary on Kind, protocol used or other factors.

When the event occurs as a result of using OpenId Connect it will include these:

Name Type Description
ClientId string The unique identifier of the client that asked to sign-in the user.
ClientName string The name of the client that asked to sign-in the user.

The JSON will be like this:

{
   ...
   metadata: {
      clientId: "UniqueClientId",
      clientName: "The perfect client"
   }
}

When the event occurs as a result of a user impersonating another user it will include these:

Name Type Description
ImpersonatedByUserId UUID The unique identity of the user impersonating the user.

The JSON will be like this:

{
   ...
   metadata: {
      impersonatedByUserId: "UniqueUserId",
   }
}

UserSignedOut

An user signed out. This event only happens when a user activly signs out, and not because of a timeout of a valid sign-in. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.usersignedout”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserSignInFailed

An user failed to sign in. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.usersigninfailed”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.
Reason numeric One of the following values indicating the reason to why the sign-in failed: 0. Invalid credentials, 1. Locked-out user, 2. Inactive user, 3. Impossible travel, 4. Module not activated for tenant or 5. Module is offline.
BreachedPasswordUsed bool true if a breached password have been used for this failed sign-in; otherwise false. If password wasn’t used or if breach detection is not configured this will be null.

UserLockedout

A user account have been locked (commonly because to many sing-in attempts). To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userlockedout”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserUnlocked

A user account have been un-locked. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userunlocked”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserDeactivated

A user account have been de-activated, which is at Valid to. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userdeactivated”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).

Note that there can be a delay until the event is pushed, but it will always be pushed in correct order.

UserReactivated

A user account have been activated again after beeing de-activated, which can be immediately or at Valid from. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userreactivated”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).

Note that there can be a delay until the event is pushed, but it will always be pushed in correct order.

UserConfirmedEmail

An user confirmed the email address. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userconfirmedemail”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

UserConfirmedPhoneNumber

An user confirmed the phone number. To retrieve only this event you use the topic “user/irm.aspnetcore.identity.events.userconfirmedphonenumber”.

Name Type Description
AggregateId UUID The unique identifier of the user (always the same as the person id for end-users).
FromIpAddress string The IP Address of the user (or service) that caused the event.
IpAddressLocation IpAddressLocation Ip address information if available.
UserAgent string The user agent string from the browser (or service) that caused the event.
Metadata dynamic A dynamic object with additional data for the event.

Subsections of Organisation module Events

ModuleActivatedForOrganisation

An organisation got a module activated. To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.moduleactivatedfororganisation”.

Name Type Description
AggregateId UUID The unique identifier of the activated module and organisation combination.
OwnerId UUID The unique identifier of the organisation.
ModuleId UUID The unique identifier of the module.

ModuleInactivatedForOrganisation

An organisation got a module in-activated. To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.moduleinactivatedfororganisation”.

Name Type Description
AggregateId UUID The unique identifier of the in-activated module and organisation combination.
OwnerId UUID The unique identifier of the organisation.
ModuleId UUID The unique identifier of the module.

ModulePayedForOrganisation

An organisation got a module set as payed (after beeing unpayed). To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.modulepayedfororganisation”.

Name Type Description
AggregateId UUID The unique identifier of the payed module and organisation combination.
OwnerId UUID The unique identifier of the organisation.
ModuleId UUID The unique identifier of the module.

ModuleUnpayedForOrganisation

An organisation got a module set as un-payed (the effect is that users from that organisation can’t sign-in until set as payed again). To retrieve only this event you use the topic “organisation/irm.aspnetcore.identity.events.moduleunpayedfororganisation”.

Name Type Description
AggregateId UUID The unique identifier of the unpayed module and organisation combination.
OwnerId UUID The unique identifier of the organisation.
ModuleId UUID The unique identifier of the module.

Subsections of Module Events

ModuleWentOffline

A module went offline. To retrieve only this event you use the topic “module/irm.aspnetcore.identity.events.modulewentoffline”.

Name Type Description
AggregateId UUID The unique identifier of the module.

ModuleWentOnLine

A module went online. To retrieve only this event you use the topic “module/irm.aspnetcore.identity.events.modulewentonline”.

Name Type Description
AggregateId UUID The unique identifier of the module.

FunctionalityDeleted

A functionality is deleted. When a functionality is deleted, the permission is also deleted from Group templates, Groups and External Systems. To retrieve only this event you use the topic “module/irm.aspnetcore.identity.events.functionalitydeleted”.

Name Type Description
AggregateId UUID The unique identifier of the module.
FunctionalityId UUID The unique identifier of the funcitonality.
Permission string The unique identifier of the permission.