SlashID Event Definitions
SlashID events are defined using protobuf. These definitions can be used to generate code for unmarshalling and handling SlashID events (for example, as received in webhook requests).
syntax = "proto3";
package events;
enum EventSource {
EventSource_UNSPECIFIED = 0;
Cloud = 1;
SDK = 2;
Gate = 3;
}
message EventMetadata {
bool is_test_event = 1;
string event_id = 2; // UUID
string timestamp = 3; // RFC3339Nano
EventSource source = 4;
string event_type = 5; // this should be constant across versions
string event_name = 6; // this includes the version - event_name = event_type + event_version
uint64 event_version = 7;
string organization_id = 8; // may not be present in all events but likely to be in the vast majority
string root_organization_id = 9;
}
// -- EVENT TYPES --
// EventTypes is a list of types of all events.
// These are not versioned - two versions of the same event have the same type
// but different names.
// Existing event types should not be removed or modified.
enum EventTypes {
EventType_UNSPECIFIED = 0;
AuthenticationSucceeded = 1;
AuthenticationFailed = 2;
VirtualPageLoaded = 3;
PersonCreated = 4;
PersonDeleted = 5;
SlashIDSDKLoaded = 6;
PersonIdentified = 7;
PersonLoggedOut = 8;
GateServerStarted = 9;
GateRequestHandled = 10;
TokenMinted = 11;
GdprConsentsChanged = 12;
PasswordChanged = 13;
AnonymousPersonCreated = 14;
AnonymousTokenMinted = 15;
}
// -- DATA TYPES --
enum PersonHandleType {
PersonHandleType_UNSPECIFIED = 0;
PhoneNumber = 1;
EmailAddress = 2;
Username = 3;
}
message PersonHandle {
PersonHandleType type = 1;
string value = 2;
}
enum PasswordChangeInitiator {
PasswordChangeInitiator_UNSPECIFIED = 0;
AdminAPI = 1;
EndUser = 2;
}
// -- METADATA --
// AnalyticsMetadata is metadata related to analytics events.
message AnalyticsMetadata {
string analytics_correlation_id = 1; // UUID
string client_ip_address = 2; // string representation of client's IP address (IPv4 or IPv6)
}
// BrowserMetadata is metadata related to events originating from a
// web browser via the SlashID SDK.
message BrowserMetadata {
string user_agent = 1;
string window_location = 2;
string slashid_sdk_version = 3;
}
// TimingMetadata is metadata related to start/end/elapsed times
message TimingMetadata {
google.protobuf.Timestamp start = 1;
google.protobuf.Timestamp end = 2;
double elapsed = 3;
}
// HttpRequestMetadata is metadata related to an HTTP request: method, url, status, bytes sent/received
message HttpRequestMetadata {
string method = 1;
string url = 2;
int32 status_code = 3;
int64 request_length = 4;
int64 response_length = 5;
}
// -- TEMPLATES --
// EventTemplate is the template for all events. All events
// will have at least the fields present in this template.
message EventTemplate {
EventMetadata event_metadata = 1;
}
// -- EVENTS --
// AuthenticationSucceeded_v1 is version 1 of the AuthenticationSucceeded analytics event.
// This event is emitted by the SDK to indicate that an authentication flow completed
// successfully.
message AuthenticationSucceeded_v1 { // source: SDK
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
BrowserMetadata browser_metadata = 3;
string person_id = 101;
string region = 102; // the region the person's data resides in
string success_authn_method = 103;
repeated string authenticated_methods = 104;
PersonHandle handle = 105; // the handle used to authenticate; not present for SSO authentications
}
// AuthenticationFailed_v1 is version 1 of the AuthenticationFailed analytics event.
// This event is emitted by the SDK or the SlashID cloud to indicate that an
// authentication flow failed.
message AuthenticationFailed_v1 { // source: SDK or Cloud
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
BrowserMetadata browser_metadata = 3; // if coming from SDK
string person_id = 101; // if previously authenticated
string region = 102; // if previously authenticated, the region the person's data resides in
repeated string authenticated_methods = 103; // if previously authenticated
string failed_authn_method = 104;
string failure_reason = 105;
string failure_detail = 106;
PersonHandle handle = 107; // the handle used in the authentication attempt; not present for SSO authentications
}
// VirtualPageLoaded_v1 is version 1 of the VirtualPageLoaded analytics event.
// This event is emitted by the SDK when a virtual page load occurs.
message VirtualPageLoaded_v1 { // source: SDK
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
BrowserMetadata browser_metadata = 3;
string person_id = 101; // if authenticated
string region = 102; // if authenticated, the region the person's data resides in
}
// PersonCreated_v1 is version 1 of the PersonCreated analytics event.
// This event is emitted by the SlashID cloud when a new person is created.
// This event is emitted for persons created through authentication and through API calls.
message PersonCreated_v1 { // source: Cloud
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
string person_id = 101;
string region = 102; // the region the person's data resides in
repeated PersonHandle handles = 103;
repeated string gdpr_consents = 104;
optional string prev_person_type = 105; // Indicates a regular person is being created from a previously different type of persons, e.g., from an anonymous person.
}
// AnonymousPersonCreated_v1 is version 1 of the AnonymousPersonCreated analytics event.
// This event is emitted by the SlashID cloud when a new anonymous person is created.
message AnonymousPersonCreated_v1 { // source: Cloud
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
string person_id = 101;
string region = 102; // the region the person's data resides in
}
// PersonDeleted_v1 is version 1 of the PersonDeleted analytics event.
// This event is emitted by the SlashID cloud when a person is deleted.
message PersonDeleted_v1 { // source: Cloud
EventMetadata event_metadata = 1;
string person_id = 101;
string region = 102; // the region the person's data resides in
repeated PersonHandle handles = 103;
repeated string groups = 104;
}
// SlashIDSDKLoaded_v1 is version 1 of the SlashIDSDKLoaded analytics event.
// It is emitted by the SDK each time it is loaded.
message SlashIDSDKLoaded_v1 { // source: SDK
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
BrowserMetadata browser_metadata = 3;
}
// PersonIdentified_v1 is version 1 of the PersonIdentified analytics event.
// It is emitted by the SDK each time the person ID held by the SDK changes to a new non-null value.
// This occurs when a person authenticates and a new token is issued, and
// when an existing token is used upon return to an application using the SlashID SDK.
message PersonIdentified_v1 { // source: SDK
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
BrowserMetadata browser_metadata = 3;
string person_id = 101;
string region = 102;
}
// PersonLoggedOut_v1 is version 1 of the PersonLoggedOut event.
// It is emitted by the SDK when a person logs out, which clears any token held
// from local storage or cookies (but does not invalidate said token).
message PersonLoggedOut_v1 { // source: SDK
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
BrowserMetadata browser_metadata = 3;
string person_id = 101;
string region = 102;
}
// TokenMinted_v1 is version 1 of the TokenMinted event.
// This event is emitted by the SlashID cloud to indicate that a new token has been minted.
message TokenMinted_v1 {
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
string token_id = 101;
string person_id = 102;
bool mint_token_api = 103; // Indicates this token was minted to a call to /persons/{person_id}/mint-token
string issued_at = 104; // RFC3339Nano
string expires_at = 105; // RFC3339Nano
optional string prev_anonymous_person_id = 106; // Indicates a sign in was performed while using an anonymous person
}
// AnonymousTokenMinted_v1 is version 1 of the AnonymousTokenMinted event.
// This event is emitted by the SlashID cloud to indicate that a new token has been minted for an anonymous person.
message AnonymousTokenMinted_v1 {
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
string token_id = 101;
string person_id = 102;
bool mint_token_api = 103; // Indicates this token was minted to a call to /persons/{person_id}/mint-token
string issued_at = 104; // RFC3339Nano
string expires_at = 105; // RFC3339Nano
}
// GdprConsentsChanged_v1 is version 1 of the GdprConsentsChanged event.
// This event is emitted by the SlashID cloud to indicate that a person's GDPR consents have been updated.
message GdprConsentsChanged_v1 {
EventMetadata event_metadata = 1;
string person_id = 101;
repeated GDPRConsent new_gdpr_consents = 102;
repeated GDPRConsent old_gdpr_consents = 103;
}
// GDPRConsent structure contains specifies the details of a GDPR consent enabled by the user
message GDPRConsent {
string consent_level = 1;
string created_at = 2; // RFC3339Nano
}
// PasswordChanged_v1 is version 1 of the PasswordChanged event.
// This event is emitted by the SlashID cloud to indicate that a person changed their password.
message PasswordChanged_v1 {
EventMetadata event_metadata = 1;
string person_id = 101;
string region = 102;
PersonHandle handle = 103; // handle to which the password reset link was sent
PasswordChangeInitiator initiated_by = 104; // indicates how the change was started (by the end user or by an admin with the API)
}
// GateServerStarted_v1 is version 1 of the GateServerStarted gate event.
// This event is emitted by a Gate server when it starts up.
message GateServerStarted_v1 { // source: Gate
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
GateServerStarted_v1_Version version = 101;
optional string comment = 102;
}
// GateServerStarted_v1_Version is a component of GateServerStarted_v1
// containing extra version information
message GateServerStarted_v1_Version {
string version = 1;
string variant = 2;
optional string build_commit = 3;
optional google.protobuf.Timestamp build_date = 4;
optional string built_by = 5;
}
// GateRequestHandled_v1 is version 1 of the GateRequestHandled gate event.
// This event is emitted by a Gate server whenever it serves a request.
message GateRequestHandled_v1 { // source: Gate
EventMetadata event_metadata = 1;
AnalyticsMetadata analytics_metadata = 2;
TimingMetadata timing_metadata = 4;
HttpRequestMetadata http_request_metadata = 5;
repeated GateRequestHandled_v1_Plugin plugins = 101;
}
// GateRequestHandled_v1_Plugin is a component of GateRequestHandled_v1
// containing extra details of each plugin used to handle the request.
message GateRequestHandled_v1_Plugin {
TimingMetadata timing_metadata = 1;
int32 plugin_index = 101;
string plugin_id = 102;
string plugin_type = 103;
google.protobuf.Value plugin_metadata = 104; // JSON Blob
repeated GateRequestHandled_v1_RoundTrip round_trips = 105;
}
// GateRequestHandled_v1_RoundTrip is a component of GateRequestHandled_v1
// containing extra details of each HTTP call performed by the request handler.
message GateRequestHandled_v1_RoundTrip {
TimingMetadata timing_metadata = 1;
HttpRequestMetadata http_request_metadata = 2;
}