Overview

Atom is the security control plane for connected software.

It gives one answer to three questions every serious platform must ask:

• Who is this user, device, service, AI agent, workload, or application?
• How did it prove its identity?
• What is it allowed to do right now?

Most products start with simple login. As they grow, they add devices, API keys, services, AI agents, tenants, certificates, roles, audit logs, and custom permission logic. That security logic often becomes scattered across many services and databases.

Atom centralizes it in one focused system.

Built for Magistrala, but generic enough for IoT, AI, SaaS, edge, and cloud-native systems.

Why it matters

Modern platforms are no longer only people logging into dashboards.

They also have:

• devices sending data;
• AI agents logging in and calling tools or APIs;
• services calling other services;
• customers separated into tenants;
• certificates used for machine identity;
• API keys used by long-running clients;
• operators and auditors asking who had access and why.

Without a shared security control plane, each product team usually builds part of this themselves. That creates duplicated work, inconsistent behavior, hidden access bugs, and weak auditability.

Atom makes those decisions consistent, visible, and reusable.

What it does

Where Atom is useful

AI agents can be represented as service, workload, or application entities, depending on how the platform runs them.

Plain-language summary

Atom is the access-control brain behind a platform.

Applications still do their own business work. IoT systems still move messages. AI platforms still run agents and workflows. Atom handles the security questions behind those systems:

Who is this?
How did it authenticate?
What can it do?
Why was it allowed or denied?
Can we audit that later?

That is the value of Atom: it turns security from scattered custom logic into a shared platform capability.

Source of truth

This docs site is an operator/developer guide. The product source of truth lives in:

• PRD
• Access model
• Magistrala integration
• Certificates

GraphQL

Atom exposes GraphQL at POST /graphql. GraphQL uses the same Bearer token authentication as Auth/OIDC REST endpoints. The schema covers health, login/logout/session lookup, tenants, profiles, profile versions, entities, resources, groups, credentials, ownerships, roles, actions, permission blocks, role assignments, Direct Policies, authz checks, audit logs, and profile-driven entity creation. Non-GraphQL public endpoints are intentionally limited to Auth/OIDC, health, JWKS, public PKI artifacts, and custom endpoint execution.

The Atom Next UI is a separate optional frontend. In Docker Compose it is enabled with the atom-ui profile and uses Atom GraphQL through ATOM_GRAPHQL_URL.

The Atom Next UI contains the GraphQL playground and API Builder. It uses GraphQL introspection and Atom GraphQL operations only, does not inspect raw database tables, and does not provide Magistrala-specific mutations or aliases.

Atom rate limits use the socket peer IP by default. X-Forwarded-For and X-Real-IP are trusted only when the immediate peer is inside ATOM_TRUSTED_PROXY_CIDRS. Keep this empty unless Atom is behind an ingress or proxy that overwrites client IP headers.

Atom GraphQL is generic. No Magistrala-specific GraphQL aliases exist; use the generic application mappings below.

GraphQL uses typed enums for Atom's fixed vocabularies, including EntityKind, EntityStatus, TenantStatus, Effect, CredentialKind, and AuditOutcome. Inline GraphQL uses enum values without quotes, such as kind: device. When using variables, send the same value as a JSON string, such as "device".

For entity creation, frontends should send profileId when a profile is selected. Atom derives the internal kind from profile.kind; if profileVersionId is omitted, Atom uses the active/latest profile version. Authorization still uses entities.kind, not profileId or profileVersionId.

mutation {
  login(input: {
    identifier: "atom-admin",
    secret: "change-me",
    kind: "password"
  }) {
    token
    entityId
    sessionId
    expiresAt
  }
}
 
mutation {
  createTenant(input: {
    name: "factory-a",
    route: "factory-a"
  }) {
    id
    name
    route
    status
  }
}
 
mutation {
  createEntity(input: {
    profileId: "client-profile-id",
    name: "meter-001",
    attributes: {
      serial_no: "WM-001"
    }
  }) {
    id
    kind
    profileId
    profileVersionId
    attributes
  }
}
 
mutation {
  createResource(input: {
    kind: "channel",
    name: "telemetry",
    attributes: {
      topic: "telemetry"
    }
  }) {
    id
    kind
    name
    attributes
  }
}
 
mutation {
  authzCheck(input: {
    subjectId: "client-entity-id",
    action: "publish",
    resourceId: "channel-resource-id"
  }) {
    allowed
    reason
  }
}

Generic application mapping uses Atom operations directly: a domain-like app calls createTenant, a client-like app calls createEntity with a device/client profile, a channel-like app calls createResource with kind="channel", a role-based app creates Permission Blocks and assigns Roles, and a strict runtime link creates a Direct Policy that references a Permission Block.

Core design principles

Entity-first — everything is an entity. There is no special "user" class. Humans, devices, and services are all modeled identically and treated symmetrically by the authorization engine.

Online authorization — tokens carry no embedded permissions. Every authorization decision calls the PDP at runtime. This means policy changes take effect immediately, without token reissuance.

Deny by default — a matching deny Permission Block overrides matching allows. No matching allow means denied.

Single binary — one Rust binary, one Postgres database. No sidecars, no service mesh required.

Where to start