Skip to main content
Understanding Golain’s resource model helps whether you use the console, CLI, or edge runtime.

​
Hierarchy

Every API call and UI screen is scoped to an org and usually a project. Fleet and device operations also require a fleet ID (or fleet name resolved by CLI tools).

​
Authentication

Golain uses Zitadel (OIDC) for human users:
  • Web console (pw) — authorization code flow; access token stored in the browser; API requests send Authorization: Bearer … and ORG-ID.
  • Platform CLI (platform-tui) — OAuth device authorization grant (RFC 8628); no client secret; token stored in ~/.config/platform-tui/profiles/.
  • Golain CLI — OAuth browser flow against production endpoints (api.ilyama.golain.io, Zitadel).
  • Devices — MQTT mTLS or username/password plus optional JITR bootstrap certificates; not user OIDC tokens.
Never put user OIDC tokens on devices. Devices use device credentials or certificates issued during enrollment.

​
Device identity and MQTT

Each MQTT device receives:
  • A stable device ID (UUID)
  • Broker endpoint (host, port, TLS)
  • Client ID and credentials or client certificate
  • Topic filters — allowed publish/subscribe patterns scoped to the device
Edge runtimes like Omega use these values in the connection: block of a client YAML profile.

​
Tags and targeting

Tags are project-scoped labels attached to devices. Use them to:
  • Filter device lists in the console and CLI
  • Target OTA deployments (target-tags=prod,eu)
  • Drive automation rules

​
OTA model

Manage releases and deployments from the console or platform-tui.

​
Integrations

External systems (LoRaWAN NS, MDM, webhooks, gateways) connect through integration accounts and bindings at the project level. The console Connections area and platform-tui integrations commands list configured providers.

​
Dataspaces

A dataspace is a project-scoped table for device and application data. You pick a modality at create (timeseries, point, state, or mutable). That choice decides append vs current values, one row vs many, and whether the cloud can push changes back to devices. See Dataspaces for the modality × layout × storage matrix, or schema and storage in detail. Jump to telemetry, point, state, or mutable.

​
Edge data sync (advanced)

Devices running Omega with the SQLite replication module can mirror local database tables to the cloud over MQTT/QUIC. The platform stages rows, runs schema review, and materializes data into dataspaces. See Edge data sync and Dataspaces.

​
Device RPC

Devices with the device-rpc Omega module expose protobuf/gRPC services tunneled over MQTT. Cloud callers invoke unary methods via the RPC host https://rpc.ilyama.golain.io (sync), server-streaming methods via the /streams/ SSE path, or enqueue unary calls for durable delivery when devices are offline — see Queued invoke. Queued delivery is at-least-once; device handlers must implement idempotency. See Device RPC. This is separate from legacy shell RPC (exec:<command> over control topics).

​
Permissions

Access is graph-based (ReBAC): grants tie users and groups to orgs, projects, fleets, and devices. The console hides actions you cannot perform; API returns 403 when a check fails. Common roles at org level: owner, admin, member, viewer. Finer grants exist at project and fleet scope.

​
URLs and environments

CLI tools let you override API and auth endpoints per profile — see Platform CLI login.