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.

​
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 project query surfaces. See Edge data sync.

​
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.