Customer Views

Customer views provide multi-tenancy for Alerta deployments that serve multiple customers or teams from a single instance. When enabled, alerts are automatically partitioned by customer so that each logged-in user only sees alerts belonging to their organisation.

A top-level customer attribute on alerts and heartbeats is used to partition data. The value is determined by a customer lookup table that maps user logins, email domains, groups, or organisation names to customer strings.

Overview

Without customer views every authenticated user sees all alerts. Customer views add an implicit filter so that:

• Customer users only see alerts tagged with their customer name.

• Admin users (those listed in ADMIN_USERS) see all alerts across every customer.

The customer value is also embedded in API keys generated by a customer user, so integrations that send alerts on behalf of that customer are automatically scoped.

Enabling Customer Views

Customer views require authentication to be enabled. Add the following to alertad.conf:

AUTH_REQUIRED = True
CUSTOMER_VIEWS = True

Then define at least one admin user who will have unrestricted access:

ADMIN_USERS = ['admin@example.com']

Important

Every non-admin user must have a matching entry in the customer lookup table. If CUSTOMER_VIEWS is True and no match is found for a user at login time, the server returns a 403 Forbidden error with the message “No customer lookup configured for user …”.

How Customer Matching Works

When a user authenticates, Alerta calls the customer lookup function with two inputs:

1. The user’s login (typically their email address).

2. A list of groups the user belongs to (OAuth organisations, LDAP groups, OIDC/SAML groups, etc.).

The lookup iterates over [login] + groups and checks each value against the match field in the customer lookup table. Every matching row’s customer value is collected and returned.

For example, given the following lookup table:

Match	Customer
example.com	Example Corp
ops-team	Example Corp
bob@partner.io	Partner Inc

• A user logging in as alice@example.com who belongs to group ops-team will match on both example.com and ops-team, resulting in customer Example Corp.

• A user logging in as bob@partner.io will match on their exact login, resulting in customer Partner Inc.

Note

The match value is compared as an exact string against the user’s login and each of their groups. It is not a regex or glob pattern. For email-domain matching, the auth provider must include the domain in the groups list (which is the default behaviour for Google and GitHub auth).

Special cases:

• If any matched customer value is *, the user is treated as having access to all customers.

• If the user’s login appears in ADMIN_USERS, the lookup short-circuits and returns all customers (admin access).

Creating Customer Lookups

Customer lookup entries are managed via the /customer API endpoint. Only users with the admin:customers scope can create, update, or delete entries.

Create a lookup

POST /customer

$ curl -X POST http://localhost:8080/api/customer \
  -H "Authorization: Key <ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "match": "example.com",
    "customer": "Example Corp"
  }'

Response:

{
  "customer": {
    "customer": "Example Corp",
    "href": "http://localhost:8080/api/customer/8e9c4736-...",
    "id": "8e9c4736-...",
    "match": "example.com"
  },
  "id": "8e9c4736-...",
  "status": "ok"
}

List all lookups

GET /customers

$ curl http://localhost:8080/api/customers \
  -H "Authorization: Key <ADMIN_API_KEY>"

Update a lookup

PUT /customer/:id

$ curl -X PUT http://localhost:8080/api/customer/<CUSTOMER_ID> \
  -H "Authorization: Key <ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "New Customer Name"
  }'

Delete a lookup

DELETE /customer/:id

$ curl -X DELETE http://localhost:8080/api/customer/<CUSTOMER_ID> \
  -H "Authorization: Key <ADMIN_API_KEY>"

How Alerts Are Filtered

When customer views are enabled the customer attribute acts as an implicit filter on all queries:

• Sending alerts – When an alert is created using an API key that belongs to a customer user, the customer field is automatically set to that user’s customer value. There is no need to include customer in the alert payload.

• Querying alerts – When a customer user queries GET /alerts, the server appends an additional filter so that only alerts matching their customer are returned.

• Heartbeats – The same filtering applies to heartbeats. Customer users only see heartbeats tagged with their customer value.

• Blackout periods – Customer users can only create blackout periods that apply to their own customer’s alerts.

This filtering is transparent and requires no changes to API calls.

Admin vs Customer Users

Capability	Admin User	Customer User
View all alerts	Yes	No (own only)
Create / delete customer lookups	Yes	No
Manage users	Yes	No
Create API keys	Any scope	Customer-scoped
Create blackout periods	Any customer	Own customer only
View heartbeats	All	Own customer only

A user is considered an admin if their login appears in the ADMIN_USERS list or if they have been assigned an admin role via ADMIN_ROLES.

Configuration Reference

The following settings in alertad.conf control customer views:

Related scopes:

• admin:customers – required to create, update, or delete customer lookup entries.

• read:customers – required to list customer lookup entries.