UBA Backend API Contract

This document organizes the UBA external/internal API contracts based on the actual Protobuf definitions (backend/api/protos/), serving as the authoritative reference for secondary development and SDK integration.

Interface contract first: all APIs are defined in .proto files, with Go / TypeScript / OpenAPI code generated via buf. See Code Generation Pipeline for details.

1. Proto Layering

api/protos/
├── uba/service/v1/        # UBA domain messages + gRPC service contracts (implemented by Core)
│   ├── analytics.proto     # Analytics aggregations
│   ├── behavior_event.proto# Behavior events
│   ├── report.proto        # Report service (implemented by Collector)
│   ├── session.proto / event_path.proto
│   ├── risk_event.proto / risk_rule.proto
│   ├── application.proto / event_schema.proto / object.proto
│   ├── tag_definition.proto / user_tag.proto / id_mapping.proto
│   ├── user_behavior_profile.proto / webhook.proto
│   ├── common.proto / uba_error.proto
├── admin/service/v1/      # Admin console HTTP gateway (forwarding implemented by Admin, i_ prefix)
│   ├── i_analytics.proto / i_behavior_event.proto / i_application.proto
│   ├── i_session.proto / i_event_path.proto / i_event_schema.proto
│   ├── i_risk_event.proto / i_risk_rule.proto / i_webhook.proto
│   ├── i_tag_definition.proto / i_user_tag.proto / i_id_mapping.proto
│   ├── i_user.proto / i_role.proto / i_permission*.proto / i_menu.proto
│   ├── i_authentication.proto / i_login_policy.proto / i_tenant.proto
│   ├── i_dict_*.proto / i_language.proto / i_file*.proto / i_task.proto
│   ├── i_internal_message*.proto / i_org_unit.proto / i_position.proto
│   └── i_*_audit_log.proto / i_admin_portal.proto
└── <other domains>/            # authentication / permission / dict / identity ...

Only admin/service/v1/*.proto generates the frontend TypeScript client (see inputs.paths in api/buf.admin.typescript.gen.yaml).

2. Report Service (Collector)

ReportService (uba/service/v1/report.proto)

HTTP Endpoint

• POST /uba/v1/report

Authentication

• appId + appSecret are placed in the request body (not headers); no Authorization token.
• Authentication failure returns 401; the SDK does not retry.

Request Body Structure (camelCase, protojson encoding)

{
  "appId": "your_app_id",
  "appSecret": "your_app_secret",
  "clientInfo": { "userAgent": "...", "referer": "..." },
  "events": [
    {
      "eventType": "BEHAVIOR",        // BEHAVIOR | RISK
      "eventId": "uuid",              // auto-generated by the SDK, unique
      "eventName": "click",           // required
      "eventTime": "RFC3339",         // auto-completed by the SDK
      "deviceId": "...",              // persisted by the SDK, stable per device
      "sessionId": "...",             // session level
      "platform": "web",              // detected by the SDK
      "userId": 1001,                 // carried automatically after identify
      "properties": { "button": "buy" },
      "behavior": { "objectType": "button", "objectId": "btn_buy" }
    }
  ]
}

tenantId is not reported; the server authoritatively identifies and overrides it based on appId, ensuring multi-tenant isolation.

Event Types (oneof payload of the events element)

Response Conventions

• HTTP 200 may still contain partial failures: when the response body has failedCount > 0 or a non-empty errorsByType, the SDK logs a warning.
• Error codes: 400 validation failure, 401 authentication failure (no retry), 500 server error (retry).
• Error bodies follow the Kratos error envelope format.

3. Analytics Aggregation Service

AnalyticsService (uba/service/v1/analytics.proto)

A total of 25 analysis model RPCs (grouped by scenario, corresponding to lines 11-83 of the proto):

Common Messages

• AnalyticsGranularity enum: UNSPECIFIED=0, HOUR=1, DAY=2, WEEK=3, MONTH=4.
• TimeRange: start_ms (inclusive), end_ms (inclusive), Unix milliseconds. When omitted, the default is end = now and start = 7 days ago.
• TimeSeriesPoint: timestamp (ms), value (double).

Request Essentials

The request messages (*Request) of the 25 models follow unified conventions:

• Common fields: time_range (TimeRange), optional app_id (used in the repository as a tenant_id isolation predicate; 0/absent means all tenants). Time-series models also carry granularity (AnalyticsGranularity).
• Filter fields: event_name / platform / dimension etc. are carried according to each model's semantics. GroupBy's dimension uses a whitelist: platform/channel/country/app_version/event_name/event_category/os/network (game models additionally support server_id/level etc.).
• Model-specific parameters: e.g. FunnelRequest.steps (repeated string, ≥2), RetentionRequest.retention_type (ACTIVE/EVENT) + max_offset_days, GroupByRequest.metric (COUNT/UNIQUE_USER/SUM_AMOUNT), etc.

For the complete field-by-field definitions of the 25 models, consult backend/api/protos/uba/service/v1/analytics.proto (request/response messages with full field comments), or the Swagger docs generated by running make openapi.

Admin HTTP Endpoints (admin/service/v1/i_analytics.proto)

All are POST with body: "*", forwarded to Core gRPC; the path convention is uniformly POST /admin/v1/analytics/<kebab-case method name>:

⚠️ Known limitation: ActiveUsers's wau/mau already output true values at the daily level based on HLL rolling windows; only HOUR granularity degrades to equal DAU due to the lack of hourly state. See Appendix for details.

4. Behavior Event Service

BehaviorEventService (uba/service/v1/behavior_event.proto)

Full Set of BehaviorEvent Fields (corresponds to events_fact)

5. CRUD Services Overview

The following services all provide standard CRUD (List/Count/Get/Create/Update/Delete, some with BatchCreate), forwarded one-to-one by the Admin layer:

For the complete request/response message definitions, consult the corresponding .proto files directly in backend/api/protos/, or the Swagger docs generated by running make openapi.

6. Getting Interactive Documentation

cd backend
make openapi   # generate OpenAPI / Swagger (based on admin / collector protos)

After starting the Admin / Collector services (enable_swagger: true), visit each service's Swagger UI to browse and try out the APIs.

7. Related Documentation

• System Architecture
• Backend Module Overview
• Code Generation Pipeline
• OLAP Query Cookbook