Skip to main content
API docs by Redocly

Entrosity Matrix Portal API (0.1.0)

Download OpenAPI specification:Download

Entrosity Matrix portal REST API: per-tenant control of computer-room internet access through FortiGate firewall policies, via an on-premises connector (rooms on/off, "disable until", address objects of the rooms' address groups, teacher room grants, history). This file is the source of truth for the backend server interfaces (oapi-codegen), request validation, and the frontend types (openapi-typescript). Run make gen after editing.

Authentication: Authorization: Bearer <product token>: users sign in on Entrosity Hub, which issues five-minute product tokens for Matrix (POST /api/platform/v1/auth/product-token {"product":"matrix"}, with the Hub's session cookie). Users, tenants (the Hub's organizations) and roles are managed on the Hub; Matrix keeps a copy.

Every route's access rule (public, authenticated, global admin, tenant permission) is declared in internal/http/portal/access.go and enforced before the handler runs.

system

Liveness probe

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

auth

Short-lived token for a tenant live stream (EventSource)

Returns a token valid for 60 seconds that opens GET /tenants/{tenantID}/stream?sse_token= for the given tenant and the caller's session. Access to the tenant is checked when the stream opens. Keeps the access token out of URLs.

Authorizations:
bearerAuth
Request Body schema: application/json
required
tenant_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "expires_in": 0
}

The signed-in user with their tenants and roles

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "display_name": "string",
  • "status": "active",
  • "is_global_admin": true,
  • "memberships": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

admin

Cross-tenant counters

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "tenants_total": 0,
  • "tenants_active": 0,
  • "global_admins": 0,
  • "tenant_users": 0,
  • "firewalls_total": 0,
  • "firewalls_online": 0,
  • "rooms_total": 0,
  • "rooms_disabled": 0,
  • "connectors_total": 0,
  • "connectors_online": 0,
  • "tenants": [
    ]
}

Stored connector releases, with download links

Every stored Matrix connector installer (the newest ten), newest first, each with a link that needs no sign-in until download_expires_at; current marks the release connectors are updated to (MATRIX_CONNECTOR_UPDATE_CHANNEL). adoption counts the enrolled connectors by version. Empty when releases are off.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "adoption": [
    ],
  • "update_channel": "stable",
  • "releases_enabled": true,
  • "public_key": "string"
}

List tenants

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
status
string (TenantStatus)
Enum: "active" "suspended"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Global admins (the platform admins of Entrosity Hub)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Cross-tenant audit log

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
tenant_id
string <uuid>
actor_user_id
string <uuid>
action
string <= 100 characters
resource_type
string <= 100 characters
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

tenant

Tenant profile

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change the tenant's settings (the name is the Hub's)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
object (TenantSettings)
default_timezone
string <= 64 characters

IANA time zone of schedules shown for firewalls without a site (default UTC).

object (TenantRetention)

Overrides of the server's retention windows (sent as a whole).

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Counters, firewall health and the last day's changes

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "connectors_total": 0,
  • "connectors_online": 0,
  • "firewalls_total": 0,
  • "firewalls_online": 0,
  • "rooms_total": 0,
  • "rooms_disabled": 0,
  • "schedules_open": 0,
  • "sites_total": 0,
  • "changes_today": 0,
  • "changes_failed_today": 0
}

Tenant members and their roles (managed on Entrosity Hub)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Sites of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
description
string <= 2000 characters
timezone
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
description
string <= 2000 characters
timezone
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a site (its connectors and firewalls stay, without a site)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Audit log of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
actor_user_id
string <uuid>
action
string <= 100 characters
resource_type
string <= 100 characters
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

connectors

Connector enrollment tokens of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a connector enrollment token (the secret is returned once)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
label
string <= 200 characters
site_id
string <uuid>
expires_at
string <date-time>
max_uses
integer [ 1 .. 100000 ]

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "max_uses": 1
}

Response samples

Content type
application/json
{
  • "token": {
    },
  • "secret": "string",
  • "install_command": "string",
  • "cli_command": "string",
  • "download_url": "string"
}

Revoke an enrollment token

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
tokenID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Delete an enrollment token permanently (global admins; requires the password)

Global admins confirm with their own password: they send step_up_token, which Entrosity Hub issues for the password (POST /api/platform/v1/auth/step-up, product matrix).

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
tokenID
required
string <uuid>
Request Body schema: application/json
required
step_up_token
required
string [ 1 .. 4096 ] characters

Responses

Request samples

Content type
application/json
{
  • "step_up_token": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

The newest connector installer, with a download link

The release connectors are updated to (MATRIX_CONNECTOR_UPDATE_CHANNEL). download_url needs no sign-in and works until download_expires_at. 404 when no release has been published.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "version": "0.1.0",
  • "channel": "stable",
  • "sha256": "string",
  • "size_bytes": 0,
  • "notes": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "download_url": "string",
  • "download_expires_at": "2019-08-24T14:15:22Z"
}

Matrix connectors of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get a connector

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "name": "string",
  • "hostname": "string",
  • "domain": "string",
  • "version": "string",
  • "capabilities": [
    ],
  • "status": "online",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "firewall_count": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Rename a connector or move it to a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>
Request Body schema: application/json
required
name
string <= 200 characters
site_id
string <uuid>
clear_site
boolean

Remove the connector from its site.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "clear_site": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "name": "string",
  • "hostname": "string",
  • "domain": "string",
  • "version": "string",
  • "capabilities": [
    ],
  • "status": "online",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "firewall_count": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Remove a connector (409 connector_has_firewalls while it serves firewalls)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

A connector job (firewall check, refresh, room switch, address change)

404 for teachers when the job concerns a room (or firewall) not granted to them.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
jobID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "firewall_id": "5b8ae62a-9fb0-43bd-91d3-a9c16b3ec753",
  • "policy_id": 0,
  • "room_code": "string",
  • "operation_id": "cb4ede3c-a5d1-45e3-a9d2-fe83accbce52",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

firewalls

The tenant's firewalls (configuration and last report)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add a firewall behind one of the tenant's connectors

The configuration is sent to the connector (matrix.firewall.apply). writes_enabled and address_writes_enabled default to false. The token is write-only (also PUT .../token). 422 with fields when the configuration is invalid (e.g. policy_pattern without a (?P<room>…) group).

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
connector_id
required
string <uuid>
site_id
string <uuid>
driver
required
string (FirewallDriver)
Enum: "fortigate" "simulator"

simulator is an in-memory FortiGate built into the connector, for trials and tests.

host
required
string [ 1 .. 253 ] characters
port
integer [ 1 .. 65535 ]
Default: 443
vdom
string [ 1 .. 79 ] characters
Default: "root"
src_intf
required
string [ 1 .. 79 ] characters
dst_intf
required
string [ 1 .. 79 ] characters
policy_pattern
required
string [ 1 .. 500 ] characters
object <= 200 properties
hostname_suffix
required
string [ 2 .. 200 ] characters
marker_prefix
string [ 1 .. 64 ] characters
verify_tls
boolean
Default: true
ca_pem
string <= 65536 characters
expected_version
string <= 20 characters
report_interval_s
integer [ 15 .. 300 ]
Default: 30
writes_enabled
boolean
Default: false
address_writes_enabled
boolean
Default: false
site_writes_enabled
boolean
Default: false
enabled
boolean
Default: true
token
string [ 1 .. 512 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "driver": "fortigate",
  • "host": "string",
  • "port": 443,
  • "vdom": "root",
  • "src_intf": "string",
  • "dst_intf": "string",
  • "policy_pattern": "string",
  • "building_labels": {
    },
  • "hostname_suffix": "string",
  • "marker_prefix": "string",
  • "verify_tls": true,
  • "ca_pem": "string",
  • "expected_version": "string",
  • "report_interval_s": 30,
  • "writes_enabled": false,
  • "address_writes_enabled": false,
  • "site_writes_enabled": false,
  • "enabled": true,
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "name": "string",
  • "driver": "fortigate",
  • "host": "string",
  • "port": 0,
  • "vdom": "string",
  • "src_intf": "string",
  • "dst_intf": "string",
  • "policy_pattern": "string",
  • "building_labels": {
    },
  • "hostname_suffix": ".coding.local",
  • "marker_prefix": "string",
  • "verify_tls": true,
  • "ca_pem": "string",
  • "expected_version": "string",
  • "report_interval_s": 0,
  • "writes_enabled": true,
  • "address_writes_enabled": true,
  • "site_writes_enabled": true,
  • "sites_supported": true,
  • "enabled": true,
  • "has_token": true,
  • "credentials_version": 0,
  • "status": "pending",
  • "status_error": "string",
  • "error_code": "string",
  • "fortios_version": "string",
  • "guard_state": "string",
  • "last_report_at": "2019-08-24T14:15:22Z",
  • "stale": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

A firewall

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "name": "string",
  • "driver": "fortigate",
  • "host": "string",
  • "port": 0,
  • "vdom": "string",
  • "src_intf": "string",
  • "dst_intf": "string",
  • "policy_pattern": "string",
  • "building_labels": {
    },
  • "hostname_suffix": ".coding.local",
  • "marker_prefix": "string",
  • "verify_tls": true,
  • "ca_pem": "string",
  • "expected_version": "string",
  • "report_interval_s": 0,
  • "writes_enabled": true,
  • "address_writes_enabled": true,
  • "site_writes_enabled": true,
  • "sites_supported": true,
  • "enabled": true,
  • "has_token": true,
  • "credentials_version": 0,
  • "status": "pending",
  • "status_error": "string",
  • "error_code": "string",
  • "fortios_version": "string",
  • "guard_state": "string",
  • "last_report_at": "2019-08-24T14:15:22Z",
  • "stale": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change a firewall (the connector receives the new configuration)

Moving the firewall to another connector removes it from the old one. Every change is re-applied (matrix.firewall.apply); a disabled firewall is removed from its connector.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
connector_id
string <uuid>
site_id
string <uuid>
clear_site
boolean
driver
string (FirewallDriver)
Enum: "fortigate" "simulator"

simulator is an in-memory FortiGate built into the connector, for trials and tests.

host
string [ 1 .. 253 ] characters
port
integer [ 1 .. 65535 ]
vdom
string [ 1 .. 79 ] characters
src_intf
string [ 1 .. 79 ] characters
dst_intf
string [ 1 .. 79 ] characters
policy_pattern
string [ 1 .. 500 ] characters
object <= 200 properties
hostname_suffix
string [ 2 .. 200 ] characters
marker_prefix
string [ 1 .. 64 ] characters
verify_tls
boolean
ca_pem
string <= 65536 characters
expected_version
string <= 20 characters
report_interval_s
integer [ 15 .. 300 ]
writes_enabled
boolean
address_writes_enabled
boolean
site_writes_enabled
boolean
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "clear_site": true,
  • "driver": "fortigate",
  • "host": "string",
  • "port": 1,
  • "vdom": "string",
  • "src_intf": "string",
  • "dst_intf": "string",
  • "policy_pattern": "string",
  • "building_labels": {
    },
  • "hostname_suffix": "string",
  • "marker_prefix": "string",
  • "verify_tls": true,
  • "ca_pem": "string",
  • "expected_version": "string",
  • "report_interval_s": 15,
  • "writes_enabled": true,
  • "address_writes_enabled": true,
  • "site_writes_enabled": true,
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "name": "string",
  • "driver": "fortigate",
  • "host": "string",
  • "port": 0,
  • "vdom": "string",
  • "src_intf": "string",
  • "dst_intf": "string",
  • "policy_pattern": "string",
  • "building_labels": {
    },
  • "hostname_suffix": ".coding.local",
  • "marker_prefix": "string",
  • "verify_tls": true,
  • "ca_pem": "string",
  • "expected_version": "string",
  • "report_interval_s": 0,
  • "writes_enabled": true,
  • "address_writes_enabled": true,
  • "site_writes_enabled": true,
  • "sites_supported": true,
  • "enabled": true,
  • "has_token": true,
  • "credentials_version": 0,
  • "status": "pending",
  • "status_error": "string",
  • "error_code": "string",
  • "fortios_version": "string",
  • "guard_state": "string",
  • "last_report_at": "2019-08-24T14:15:22Z",
  • "stale": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove a firewall (the connector forgets it and its token; the history stays)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Store the FortiGate REST API token (write-only)

Stored encrypted, never returned; bumps credentials_version and re-applies the firewall.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
Request Body schema: application/json
required
token
required
string [ 1 .. 512 ] characters

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Read-only check of the firewall (version, direction, rooms, groups, warnings)

Creates a matrix.firewall.check job; its result (GET /jobs/{jobID} or job.update) is a CheckResult. 409 connector_offline.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "firewall_id": "5b8ae62a-9fb0-43bd-91d3-a9c16b3ec753",
  • "policy_id": 0,
  • "room_code": "string",
  • "operation_id": "cb4ede3c-a5d1-45e3-a9d2-fe83accbce52",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

Read the firewall now (rooms, address groups or both)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
Request Body schema: application/json
required
scope
required
string
Enum: "rooms" "addresses" "all"

Responses

Request samples

Content type
application/json
{
  • "scope": "rooms"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "firewall_id": "5b8ae62a-9fb0-43bd-91d3-a9c16b3ec753",
  • "policy_id": 0,
  • "room_code": "string",
  • "operation_id": "cb4ede3c-a5d1-45e3-a9d2-fe83accbce52",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

rooms

Rooms of every firewall with their state and what the caller may do

Teachers see only the rooms granted to them and the firewalls they hold a room on (firewalls keeps such a firewall even before its rooms are reported, for its stale and connection state); a teacher without grants gets empty lists. Tenant admins, global admins and viewers see every room.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
firewall_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "firewalls": [
    ],
  • "rooms": [
    ]
}

Switch a room's internet access on or off

Records the change (change) and sends a matrix.policy.set job. reenable_at (disable only, 5 minutes to 7 days ahead) switches the room on again then; enabling cancels a pending re-enable. Errors: 403 forbidden; 404 unknown_room (for teachers also every room not granted to them, which they do not see); 409 busy, snapshot_stale, connector_offline, writes_disabled, unknown_room (the firewall does not report the room); 429 rate_limited. Refused attempts are recorded too.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
room
required
string [ 1 .. 64 ] characters
Request Body schema: application/json
required
status
required
string (PolicyStatus)
Enum: "enable" "disable"
reenable_at
string <date-time>

Disable only: switch on again then (5 minutes to 7 days ahead).

Responses

Request samples

Content type
application/json
{
  • "status": "enable",
  • "reenable_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "change": {
    },
  • "job": {
    }
}

Switch several rooms (a list or a building) at once

Teachers must hold a grant for every listed room, otherwise nothing is sent (404 unknown_room: rooms not granted to them do not exist for them); a building means its rooms granted to them. Each room counts against the rate limits. A room with a change already running is skipped (items[].error = busy).

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
Request Body schema: application/json
required
status
required
string (PolicyStatus)
Enum: "enable" "disable"
rooms
Array of strings [ 1 .. 2000 ] items [ items [ 1 .. 64 ] characters ]
building
string [ 1 .. 64 ] characters

Every present room of the building (when rooms is not given).

reenable_at
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "status": "enable",
  • "rooms": [
    ],
  • "building": "string",
  • "reenable_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "bulk": {
    }
}

A bulk action with the outcome of each room

404 for teachers when any of its rooms is not granted to them.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
bulkID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firewall_id": "5b8ae62a-9fb0-43bd-91d3-a9c16b3ec753",
  • "desired": "enable",
  • "building": "string",
  • "rooms": [
    ],
  • "reenable_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "items": [
    ]
}

Re-enable schedules ("disable until")

Teachers get only the schedules of the rooms granted to them.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
status
string (ScheduleStatus)
Enum: "pending" "firing" "done" "cancelled" "failed"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Cancel a pending re-enable (the room stays off)

409 schedule_not_pending when it is already firing or finished; 404 unknown_room for a teacher when the room is not granted to them (recorded as refused).

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
scheduleID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firewall_id": "5b8ae62a-9fb0-43bd-91d3-a9c16b3ec753",
  • "room_code": "string",
  • "policy_id": 0,
  • "reenable_at": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_by_email": "string",
  • "disable_job_id": "cdb01658-22b2-4b65-a10e-06515d33a85d",
  • "enable_job_id": "9ae42c9e-6bce-4b61-a6f2-f5b3f470aa2b",
  • "bulk_id": "2cabd00a-c72a-41d3-b208-4522c30a8fd2",
  • "detail": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

addresses

Address groups of the firewall's rooms (without members)

Teachers get only the groups of the rooms granted to them, and 404 for a firewall they hold no room on.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "stale": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "error": "string"
}

One address group with its members and the caller's unfinished operations

policy_id and group are required (422 when missing). 404 for a teacher when the group's room is not granted to them.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
query Parameters
policy_id
integer <int64> [ 1 .. 4294967295 ]
group
string [ 1 .. 255 ] characters

Responses

Response samples

Content type
application/json
{
  • "group": {
    },
  • "operations": [
    ],
  • "stale": true,
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change the IP of a computer's /32 address object

Tenant admins only. request_id makes the request idempotent (the same request returns the same operation). 409 conflict when the group changed since group_version, busy while another address change of the firewall runs.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
Request Body schema: application/json
required
policy_id
required
integer <int64> [ 1 .. 4294967295 ]
group
required
string [ 1 .. 255 ] characters
name
required
string [ 1 .. 255 ] characters
ip
required
string <= 15 characters
expected_ip
required
string <= 15 characters
group_version
required
string^[0-9a-f]{64}$
request_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "policy_id": 1,
  • "group": "string",
  • "name": "string",
  • "ip": "string",
  • "expected_ip": "string",
  • "group_version": "string",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846"
}

Response samples

Content type
application/json
{
  • "operation": {
    },
  • "job": {
    },
  • "change": {
    }
}

Add a computer (/32 address object) to a room's address group

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
Request Body schema: application/json
required
policy_id
required
integer <int64> [ 1 .. 4294967295 ]
group
required
string [ 1 .. 255 ] characters
name
required
string [ 1 .. 255 ] characters
ip
required
string <= 15 characters
group_version
required
string^[0-9a-f]{64}$
request_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "policy_id": 1,
  • "group": "string",
  • "name": "string",
  • "ip": "string",
  • "group_version": "string",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846"
}

Response samples

Content type
application/json
{
  • "operation": {
    },
  • "job": {
    },
  • "change": {
    }
}

An address operation and how far it got

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
operationID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firewall_id": "5b8ae62a-9fb0-43bd-91d3-a9c16b3ec753",
  • "actor_id": "04f37679-bfbf-4906-b749-01756515cecf",
  • "kind": "update",
  • "policy_id": 0,
  • "room": "string",
  • "group_name": "string",
  • "object_name": "string",
  • "desired_ip": "string",
  • "previous_ip": "string",
  • "group_version": "string",
  • "stage": "prepared",
  • "address_uuid": "string",
  • "result": "pending",
  • "last_job_id": "ff50ec87-6f42-4569-b426-b1e2ecfdfc0f",
  • "retryable": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Resume an interrupted address operation (only its author)

409 not_retryable when it never started writing (prepared) or is done.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
operationID
required
string <uuid>
Request Body schema: application/json
required
group_version
required
string^[0-9a-f]{64}$

Responses

Request samples

Content type
application/json
{
  • "group_version": "string"
}

Response samples

Content type
application/json
{
  • "operation": {
    },
  • "job": {
    },
  • "change": {
    }
}

sites

Allowed sites of a firewall (shared list and per-room lists)

Domains the rooms' computers can still reach while a room's internet is off, as last reported by the connector. rooms holds a list for every present room (exists: false when its address group is not set up). can_edit says whether the caller may change a list (tenant admins: every list; teachers: the lists of rooms granted to them). Readable by everyone who can read rooms; teachers get the shared list (read only) and the lists of the rooms granted to them, and 404 for a firewall they hold no room on.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "firewall": {
    },
  • "shared": {
    },
  • "rooms": [
    ],
  • "can_setup": true
}

FortiOS CLI that creates the missing allowed-sites groups and policies (tenant admins)

Text to paste into the FortiGate CLI: the address groups (member "none") and ACCEPT policies (edit 0, the firewall's source → destination, srcaddr = the room address groups) of the shared list and the per-room lists named in rooms, only where they are missing. Matrix never creates policies itself.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
query Parameters
rooms
string <= 20000 characters

Comma-separated room codes whose per-room lists should be set up too.

Responses

Response samples

Content type
application/json
{
  • "cli": "string",
  • "lists": [
    ],
  • "warnings": [
    ]
}

Replace the domains of an allowed-sites list

domains is the full desired set of Matrix-managed domains (canonicalized: lower-case, sorted, duplicates removed; at most 200). Records the change (change, kind sites) and sends a matrix.sites.set job. The shared list: tenant admins only; a per-room list: tenant admins and teachers the room is granted to. Errors: 403 forbidden / group_read_only (Matrix may not change the group on the FortiGate); 409 busy, conflict (the list changed since list_version), snapshot_stale, connector_offline, connector_outdated (the connector does not support allowed sites yet), writes_disabled (allowed-sites editing is off for the firewall), sites_not_set_up, unknown_room; 404 unknown_room for a teacher when the room is not granted to them; 422 invalid_domain; 429 rate_limited. Refused attempts are recorded too.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
firewallID
required
string <uuid>
list
required
string [ 1 .. 64 ] characters

shared or a room code.

Request Body schema: application/json
required
domains
required
Array of strings <= 200 items [ items [ 1 .. 253 ] characters ]
list_version
required
string^[0-9a-f]{64}$

Responses

Request samples

Content type
application/json
{
  • "domains": [
    ],
  • "list_version": "string"
}

Response samples

Content type
application/json
{
  • "change": {
    },
  • "job": {
    }
}

grants

Which teachers may switch which rooms (non-admins see their own)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
user_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Replace a teacher's rooms on one firewall

Recorded as a grants change. Rooms to add must be known rooms of the firewall; removing is always possible. 422 not_teacher when the user is not a teacher of the tenant.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
userID
required
string <uuid>
Request Body schema: application/json
required
firewall_id
required
string <uuid>
rooms
required
Array of strings <= 2000 items [ items [ 1 .. 64 ] characters ]

Responses

Request samples

Content type
application/json
{
  • "firewall_id": "5b8ae62a-9fb0-43bd-91d3-a9c16b3ec753",
  • "rooms": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

history

The change history, newest first (cursor pagination)

Teachers get only the changes of the rooms granted to them (including their own refused attempts on those rooms); changes without a room (firewall, grant, shared-list changes) are left out.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
from
string <date-time>
to
string <date-time>
user_id
string <uuid>
room
string <= 64 characters

Part of a room code (case-insensitive).

kind
string (ChangeKind)
Enum: "policy" "address_update" "address_create" "grants" "schedule" "bulk" "sites" "services"

What a change did. services is read-only history: the removed Entrosity services group (no new changes of this kind are made).

firewall_id
string <uuid>
cursor
string <= 200 characters

next_cursor of the previous page.

limit
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

events

Live updates (server-sent events)

text/event-stream of the tenant's live updates: matrix.rooms ({firewall_id}: reload the rooms), matrix.addresses ({firewall_id}: reload the address groups), matrix.sites ({firewall_id}: reload the allowed sites), matrix.change (a change event finished), connector.status and job.update. Authenticate with a bearer token or, for EventSource, ?sse_token= from POST /auth/sse-token. Teachers get only the events of the rooms granted to them (matrix.change: changes of those rooms; job.update: their jobs) and of the firewalls they hold a room on.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
sse_token
string <= 4096 characters

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}