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 external 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;
  PermissionCreated_InRegion = 16;
  PermissionCreated = 17;
  PermissionDeleted_InRegion = 18;
  PermissionDeleted = 19;
  RoleCreated_InRegion = 20;
  RoleCreated = 21;
  RoleDeleted_InRegion = 22;
  RoleDeleted = 23;
  RoleUpdated_InRegion = 24;
  RoleUpdated = 25;
  RolesSetToPerson_InRegion = 26;
  RolesSetToPerson = 27;
  PermissionUpdated_InRegion = 28;
  PermissionUpdated = 29;
  GateRequestCredentialFound = 30;
  MitmAttackDetected         = 31;
}

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

message AuthenticationDetails {
  string                timestamp = 1; // RFC3339Nano
  string                method    = 2; // one of the supported factor methods (https://developer.slashid.dev/docs/access/sdk/modules/Types#factormethod-1)
  optional PersonHandle handle    = 3; // only present for factor methods that allow it
}

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

message FoundExternalCredential {
  string credential_id   = 1; // UUID
  string credential_type  = 2;
  string credential_value = 3;
  string credential_provider = 4;
  string credential_hash = 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
  bool                           first_token              = 107;
  repeated AuthenticationDetails authentications          = 108;
}

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

message GateRequestCredentialFound_v1 { // source: Gate
  EventMetadata event_metadata = 1;
  AnalyticsMetadata analytics_metadata = 2;
  TimingMetadata timing_metadata            = 3;
  HttpRequestMetadata http_request_metadata = 4;

  FoundExternalCredential credential = 101;
  string gate_identifier = 102;
}

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

message PermissionCreated_InRegion_v1 {
  EventMetadata event_metadata = 1;

  string permission_name = 2;
  string description = 3;

  string region = 100;
}

message PermissionCreated_v1 {
  EventMetadata event_metadata = 1;
  string permission_name = 2;
  string description = 3;
}

message PermissionDeleted_InRegion_v1 {
  EventMetadata event_metadata = 1;
  string permission_name = 2;

  string region = 100;
}

message PermissionDeleted_v1 {
  EventMetadata event_metadata = 1;
  string permission_name = 2;
}

message RoleCreated_InRegion_v1 {
  EventMetadata event_metadata = 1;

  string role_name = 2;
  string description = 3;
  repeated string permissions = 4;

  string region = 100;
}

message RoleCreated_v1 {
  EventMetadata event_metadata = 1;

  string role_name = 2;
  string description = 3;
  repeated string permissions = 4;
}

message RoleDeleted_InRegion_v1 {
  EventMetadata event_metadata = 1;
  string role_name = 2;

  string region = 100;
}

message RoleDeleted_v1 {
  EventMetadata event_metadata = 1;
  string role_name = 2;
}

message RoleUpdated_InRegion_v1 {
  EventMetadata event_metadata = 1;

  string role_name = 2;
  string description = 3;
  repeated string permissions = 4;

  string region = 100;
}

message RoleUpdated_v1 {
  EventMetadata event_metadata = 1;

  string role_name = 2;
  string description = 3;
  repeated string permissions = 4;
}

message PermissionsSetToPerson_InRegion_v1 {
  EventMetadata event_metadata = 1;

  repeated string new_permissions = 2;
  repeated string old_permissions = 3;

  string person_id = 4;

  string region = 100;
}

message PermissionsSetToPerson_v1 {
  EventMetadata event_metadata = 1;

  repeated string new_permissions = 2;
  repeated string old_permissions = 3;

  string person_id = 4;
}

message RolesSetToPerson_InRegion_v1 {
  EventMetadata event_metadata = 1;

  repeated string new_roles = 2;
  repeated string old_roles = 3;

  string person_id = 4;

  string region = 100;
}

message RolesSetToPerson_v1 {
  EventMetadata event_metadata = 1;

  repeated string new_roles = 2;
  repeated string old_roles = 3;

  string person_id = 4;
}

message PermissionUpdated_InRegion_v1 {
  EventMetadata event_metadata = 1;

  string permission_name = 2;
  string description = 3;

  string region = 100;
}

message PermissionUpdated_v1 {
  EventMetadata event_metadata = 1;

  string permission_name = 2;
  string description = 3;
}

message MitmAttackDetected_v1 { // source: edge function
  EventMetadata event_metadata  = 1;

  string          client_ip_address = 101;
  string          user_agent        = 102;
  string          mitm_domain       = 103;
  repeated string allowed_domains   = 104;
  string          token_tag         = 105;
  string          mitm_token        = 106;
}