MachineQ Developer Documentation logo DOCS
Back to Docs

Roles & Permissions

Managing who can do what across your IoT deployment is critical, especially as your team grows. MQcentral's permissions system gives subscribers full control over access by letting you create custom roles tailored to your organization's needs.

The Basics: Three Permission Domains

Every action in MQcentral falls under one of three domains:

  • User Administration: Managing applications, roles, and user accounts
  • Device Administration: Managing devices, device groups, alerts, output profiles, decoder types, and device data
  • Gateway Administration: Managing gateways, gateway groups, and maintenance windows

CRUD Permissions

For each domain, you can grant four levels of access independently:

Permission What It Controls
Create Adding new resources (devices, users, gateways, etc.)
Read Viewing resources and their data (health stats, payloads, logs)
Update Modifying existing resources and their configurations
Delete Removing resources and their associated data

These are fully independent; you can grant a role Read access to devices without giving it Create, Update, or Delete. Mix and match to fit your use case.

Creating a Custom Role

As a subscriber, you can create a role with any name and assign it any combination of domain + CRUD permissions. There's no fixed template; you define exactly what each role can and can't do.

For example, you might create a role called "Field Technician" that has Read and Update access to Gateways but nothing else. Or a "Data Analyst" role that can only Read device data.

Example Custom Roles to Get You Started

Here are some roles we see subscribers create frequently:

Data Analyst

"I need to view device data but shouldn't change anything."

  • Device Administration: Read only
  • Gateway Administration: None
  • User Administration: None

Perfect for team members who need to pull reports, monitor device health, and view payloads without any risk of accidental changes.

Field Technician

"I install and maintain devices and gateways in the field."

  • Device Administration: Create, Read, Update
  • Gateway Administration: Create, Read, Update
  • User Administration: None

Technicians can register new devices/gateways, update configurations, set maintenance windows, and check on device connectivity, but can't delete resources or touch user accounts.

Security Auditor

"I need visibility into everything but can't modify anything."

  • Device Administration: Read only
  • Gateway Administration: Read only
  • User Administration: Read only

Full read access across all three domains. Ideal for compliance reviews and security audits.

Device Provisioner

"I onboard new devices in bulk but don't manage the network."

  • Device Administration: Create, Read
  • Gateway Administration: None
  • User Administration: None

Can register individual or bulk devices and verify they're online, but can't modify or delete existing devices.

Team Lead

"I manage my team's accounts and oversee our devices."

  • Device Administration: Read, Update
  • Gateway Administration: Read only
  • User Administration: Create, Read, Update

Can onboard new team members, adjust user roles, and update device configurations, without the ability to delete anything.

Full Operator

"I run the day-to-day across devices and gateways."

  • Device Administration: Create, Read, Update, Delete
  • Gateway Administration: Create, Read, Update, Delete
  • User Administration: None

Complete control over the IoT infrastructure without access to user management. Keeps operational and administrative concerns separate.

Best Practices

  1. Start with least privilege. Give each role only the permissions it needs. You can always expand later.
  2. Separate operational and administrative access. The people managing gateways in the field shouldn't necessarily be managing user accounts.
  3. Use descriptive role names. "Q4 Intern: Readonly" is more useful than "Role 7" six months from now.
  4. Audit periodically. Review your custom roles as your team evolves. Remove permissions that are no longer needed.
  5. Avoid giving Delete broadly. Delete permissions are rarely needed for day-to-day work. Reserve them for senior roles.

Wrapping Up

MQcentral's custom roles let you model your actual organizational structure, not the other way around. Whether you have a team of three or three hundred, you can ensure everyone has exactly the access they need and nothing more.

Ready to set up your first custom role? Head to Account -> Role Management -> Add a Role in MQcentral, or create one using the Roles API.

What's Next?

Quick Start Authentication & API Access