Licenses: serve your own customers

A license represents one of your customers inside your project. Each license has its own users, its own options and its own sites, so your customer can see and manage what's theirs without access to the rest of your project. You manage licenses in Connect or through the Public API.

Before you begin

You hold project_manager on the project, or container_admin on the organization. See Roles and permissions.
You have access to Connect, and the fun CLI logged in or a token for the Public API.
You know your <project-id>.

How it works

Project
 ├── License type "Parking"          declares the options its licenses carry
 │     ├── capacity     Number   required
 │     └── is_covered   True/False   default false
 │
 ├── License "Downtown garage"       of type Parking
 │     ├── options       capacity = 450, is_covered = true
 │     ├── meta_data     free-form JSON
 │     ├── users         license_manager, license_viewer
 │     └── sites ──▶ zones
 └── License "North lot"             of type Parking

A license type belongs to a project and declares option fields. Each field has a name (used by API callers), a label (shown in Connect), a type (Text, Number or True/False), and optionally a default value and a required flag.
A license is a name, one value per option field of its type, and a free-form meta_data object. Your applications read these to decide what a customer is entitled to.
License users don't need to belong to the project. That's how you give a customer's staff access to their license and nothing else.

1. Define a license type

In Connect, open your project's settings and go to License types. Create a type and add its option fields. Adding a field later gives every existing license of that type the field at its default value.

2. Create a license

In Connect, go to Licenses and select Create License. Or use the API, with the license type ID and one entry per option field:

fun api v2 licenses create-license --project-id <project-id> --body '{
  "name": "Downtown garage",
  "license_type_id": <license-type-id>,
  "options": [
    {"license_option_field_id": <capacity-field-id>, "value": 450},
    {"license_option_field_id": <is-covered-field-id>, "value": true}
  ],
  "meta_data": {"customer_ref": "ACME-001"}
}'

A required option must have a non-empty, non-zero value. List licenses with fun api v2 licenses list-licenses --project-id <project-id>: each one includes its license_type and its options with field_id, field_name and value.

3. Invite your customer's users

Two roles apply to a license:

Role	Can
`license_manager`	Read and change the license, and manage users on it and on every site under it
`license_viewer`	See the license, nothing more

Invite a user by email. container_item_id is the license ID:

fun api v2 licenses-users-invitations create-license-invitation \
  --project-id <project-id> --license-id <license-id> --body '{
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "role_id": <license-manager-role-id>,
  "container_item_id": <license-id>,
  "options": {},
  "redirect_url": "https://app.example.com/",
  "custom_message": "Welcome to your parking dashboard."
}'

The user receives an email and lands on redirect_url after signing in. See Roles and permissions for invitation statuses and how to find a role_id.

4. Add sites

Sites are your customer's locations. In Connect, open the license, select Sites, then New Site, and enter a name and an address. Sites can be divided into zones (floors, rooms, parking levels), each with its own 2D plan.

5. Give access to a single site

To give someone access to one site only, invite them on that site:

fun api v2 sites-users-invitations create-site-invitation \
  --project-id <project-id> --license-id <license-id> --site-id <site-id> --body '{
  "name": "Sam Lee",
  "email": "sam.lee@example.com",
  "role_id": <role-id>,
  "container_item_id": <site-id>,
  "options": {},
  "redirect_url": "https://app.example.com/"
}'

A license manager, a project manager and an organization administrator can all manage the users of a site, each from their own level.

Restrict who can join

In Connect, a project, a license or a site can carry a user policy: a list of allowed email domains, and whether accounts must sign in with Google, Microsoft or either. A license can't be more permissive than its project.

What's next

API reference in Swagger UI: Licenses, Licenses: Users/Invitations, Sites: Users/Invitations
Roles and permissions
Alerts: alerts can be resolved per license with fun api v1 alert resolve-alert-by-license-and-alert-id.
Query your data with Insight
Glossary