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
}
// -- 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.
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;
}
// -- DATA TYPES --
enum PersonHandleType {
EmailAddress = 0;
PhoneNumber = 1;
}
message PersonHandle {
PersonHandleType type = 1;
string value = 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;
}
// 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;
}
// 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
}
// 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;
}
// 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 requesst.
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;
}