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;
  string      event_name      = 6;
  uint64      event_version   = 7;
  string      organization_id = 8;
}

// -- EVENT TYPES --

enum EventTypes {
  EventType_UNSPECIFIED   = 0;
  AuthenticationSucceeded = 1;
  AuthenticationFailed    = 2;
  VirtualPageLoaded       = 3;
  PersonCreated           = 4;
  PersonDeleted           = 5;
}

// -- 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;
}

// 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;
}

// -- 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 {
  EventMetadata     event_metadata     = 1;
  AnalyticsMetadata analytics_metadata = 2;
  BrowserMetadata   browser_metadata   = 3;

  string          person_id             = 101;
  string          region                = 102;
  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
  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
}

// PersonCreated_v1 is version 1 of the PersonCreated analytics event.
// This event is emitted by the SlashID cloud when a new person is created.
message PersonCreated_v1 {
  EventMetadata     event_metadata     = 1;
  AnalyticsMetadata analytics_metadata = 2;

  string person_id = 101;
  string region    = 102;
}

// 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;
  repeated PersonHandle handles   = 103;
  repeated string       groups    = 104;
}