Roles and permissions

Fundamentum uses role-based access control: a role is a set of permissions, and you grant it to a person or a service account on one specific project, license or site. People get roles through email invitations; machines get them through service accounts.

Before you begin

You hold a role that can manage users where you grant access: project_manager on the project, license_manager on a license, or container_admin on the organization.
You have access to Connect, and the fun CLI logged in or a token for the Public API. See Authentication.
You know your <project-id>.

How it works

User or service account ── holds ──▶ Role ── granted on ──▶ one item: a project, a license, a site
                                      │
                                   bundles
                                      ▼
                     Permission = action + container + scope

A container is a kind of thing permissions apply to: organization, project, device, license, site, Insight, functions, and others. Containers nest, so a role granted on a project reaches the licenses and sites under it.
An action is what can be done on a container: list, show, store, update, delete, manage-users, and for functions invoke, upload and monitor.
The scope is All (every item of that kind) or Own (only the item the role was granted on).
A role is never granted in the abstract: it's "project manager on this project".

One match is enough: a license manager and a project manager can both manage the users of the same site, each from their own level.

1. Pick a role

These roles come with every installation:

Role	Granted on	Can
`project_viewer`	A project	Read the project, its devices, sites and alerts. Manage their own reports
`project_manager`	A project	Everything `project_viewer` can, plus create and change devices, sites, licenses and reports, and manage users
`devices_manager`	A project	Everything on devices, and manage alert notifiers
`devices_viewer`	A project	Read devices and alerts
`insight_manager`	A project	Everything on Insight and its users
`function_manager`	A project	Everything on cloud functions, including upload, invoke and monitor
`functions_invoker`	A project	Run and monitor cloud functions, without changing them
`license_manager`	A license	Read and change the license, and manage users on it and its sites
`license_viewer`	A license	See the license
`insight_user_manager`	A license	Manage Insight users on that license
`container_admin`	The organization	Everything, including organizations, projects, Insight and functions
`global_viewer`	The organization	Read everything, change nothing
`global_functions_manager`	The organization	Everything on cloud functions, in every project

Role IDs depend on the environment. To find them, list the containers, then the roles of the one you grant on (project, license or location for sites):

fun api v2 authorization-containers list-containers --project-id <project-id>
fun api v2 authorization-container-roles list-container-roles --project-id <project-id> --container-id <container-id>

2. Invite a user

In Connect, open Users, select New User, and choose the role, name, email and an optional message. Or use the API. For a project, container_item_id is the project ID:

fun api v2 projects-users-invitations create-invitation --project-id <project-id> --body '{
  "name": "Alex Martin",
  "email": "alex.martin@example.com",
  "role_id": <role-id>,
  "container_item_id": <project-id>,
  "options": {},
  "redirect_url": "https://hub.example.com/",
  "custom_message": "Welcome to the fleet project."
}'

An invitation is pending until the user completes it, then completed once the role is assigned. It completes immediately when the user already has a working account, already holds that role on that item, or invited themselves. One invitation carries one role: invite the same person again for each extra role. For licenses and sites, see Licenses.

3. Review and revoke access

fun api v2 projects-users-invitations list-invitations --project-id <project-id>
fun api v2 projects-users-invitations delete-invitation --project-id <project-id> --invitation-id <invitation-id>

Deleting a completed invitation removes the role. A pending invitation can still be edited with update-invitation.

4. Create a service account for automation

A service account is a non-human identity for your scripts, CI pipelines and integrations. It belongs to one project.

# Create it
fun api v2 service-accounts create-service-account --project-id <project-id> --body '{"name": "ci-deployer"}'

# Grant it a project role
fun api v2 service-accounts create-service-account-role --project-id <project-id> \
  --service-account-id <service-account-id> --body '{"role_id": <role-id>}'

# Issue a token
fun api v2 service-accounts create-service-account-token --project-id <project-id> \
  --service-account-id <service-account-id> --body '{"name": "pipeline"}'

The token is in accessToken, and it's shown only once: store it in your secret manager. Use it as Authorization: Bearer $TOKEN, or with the CLI through its environment variables (see The fun CLI). Delete a leaked or unused token with delete-service-account-token.

Grant the narrowest role that does the job, for example functions_invoker for a pipeline that only runs functions.

5. Define your own containers (advanced)

A project can secure its own resources by defining containers. A new container gets list, show, store, update and delete automatically. Add other actions, such as manage-users, yourself:

fun api v2 authorization-containers create-container --project-id <project-id> \
  --body '{"slug": "project-<project-id>-parking-gates", "name": "Parking gates"}'
fun api v2 authorization-container-actions create-container-action --project-id <project-id> --container-id <container-id> \
  --body '{"name": "open", "label": "Open gate", "short_label": "Open gate (All)", "scope": "global"}'

Then grant the actions to a role in Connect. Your applications check them through fun api v2 users introspect-user, which returns the caller with their roles and permissions.

What's next

API reference in Swagger UI: Projects: Users/Invitations, Service Accounts, Authorization: Containers
Licenses: serve your own customers
Alerts: notify users or everyone holding a role.
Authentication