SpectreGrid logo
API docs by Redocly

SpectreONE API (3.7.1)

Download OpenAPI specification:

API for managing AAAA (Authorization, Authentication, Accounting and Auditing), and device control within the SpectreGrid ecosystem.

This API enables the control, registration, and manipulation of core assets through a model of Explicit Relationships and Transfers.

Resources

  • Entities: Primary subjects of authorization, holding exactly one role and operating within explicitly defined scopes.
  • Sessions: Authentication and session management for entities.
  • Solution Templates: Blueprints defining capabilities and supported device types for solution provisioning.
  • Solutions: Deployed instances of solution templates, containing zones, devices, and users.
  • Devices: Resources that can be transferred between entities, solutions, and zones.
  • Zones of Permissions: Geographical boundaries that dynamically resolve permissions based on device location.

Core Authorization Model

Administrative authority and delegation are expressed exclusively through roles, permissions, and parent-child relationships.

The operational scope of any actor is governed by:

  • Entities
  • Solutions
  • Zones of Permissions

Note: Every solution has a Global zone that grants access to all entities within the solution.

Permissions

Permissions determine which actions an entity instance is allowed to perform, both at the API level and within the user interface. They are atomic and classified as:

  • Mandatory: Always active for the role.
  • Optional: Activated per instance by a parent entity or administrator.

Structure

A permission identifier is composed of three segments, following the format: <solution>_<object>_<permission>. Key constraints: snake_case.

  • <solution> — The short identifier of the service:

    • one: SpectreONE
    • os: OpenSesame
    • sd: SpectreDASHBOARD

  • <object> — The logical entity on which the permission operates:

    • For one: entity, session, solution, template, zone, device, user.
    • For os: device, station, gateway, position.

  • <permission> — The action authorized (e.g., create, read, update, delete).

Example: os_position_#c (Grants permission to create positions in OpenSesame).

Parameterized Permissions

Some permissions restrict their scope to specific object identifiers: <solution>_<object>_<permission>([<parameter>])

  • [<parameter>] — A list of unique identifiers of the corresponding <object> to which the permission is limited.

Distribution Actions

Distribution actions are operations that allow resources to be distributed among entities, solutions, and zones.

  • Transfer: Moves devices between person entities.
  • Assign: Allocates a device from a person entity to a solution.
  • Localize: Places a device within a specific zone. When a device is assigned to a solution, it is automatically localized to the Global Zone.
    • Localize Automatically: If devices have geo-location capabilities, they will be automatically located within the zone that contains them.
    • Localize Manually: If devices do not have geo-location capabilities, they will be located within the manually assigned zone. Their location point will be the center of the zone.

Special entrypoints: [BATCH]

Entrypoints named with [BATCH] indicate that the operation admits multiple entity operations in a single request.

Session

Endpoints related to session lifecycle management and credential issuance within the platform.

It includes:

  • Sign-in and Sign-out operations
  • Session refresh and rotation
  • Password recovery and reset
  • Account activation

Security responsibilities:

  • Authenticates identities using multiple mechanisms (Basic Authentication, Bearer Tokens, API Keys).
  • Issues short-lived JWT access tokens used to authorize requests to protected resources.
  • Manages long-lived opaque refresh tokens used to safely refresh authenticated sessions.
  • Enforces token rotation and invalidation to mitigate replay and token leakage risks.

Authorization scope:

  • Access tokens issued by these endpoints grant authorization to act on behalf of:
    • Entity instances (ENTITY)
    • End-user accounts (USER)
    • Service or application entities
  • In B2B scenarios, issued access tokens authorize access to solution-scoped resources according to assigned roles, permissions, and resolved scopes.

These endpoints represent the trust boundary where authentication transitions into authorization for both human users and services.

Create a session

Creates or refreshes an authenticated session and issues a new short-lived JWT access token.

This endpoint follows the OAuth 2.0 Bearer Token usage model as defined in RFC 6750 and applies a system-specific session lifecycle aligned with the OAuth 2.0 framework (RFC 6749).

The behavior of this endpoint depends on the authentication mechanism used:

Human user authentication (password-based)

BasicAuth + SolutionID

  • Used by persons (human users).
  • Authenticates the user using email and password credentials.
  • The API key identifies the client application.
  • Creates a new authenticated session.
  • Issues a short-lived JWT access token and a refresh session token.

Service / B2B authentication

X-API-Key + SolutionID

  • Used by services or B2B integrations.
  • Authenticates a non-human client using an existing OAuth-compatible opaque bearer token.
  • The API key identifies the calling system.
  • Creates a service-level authenticated session.
  • Issues a short-lived JWT access token representing the service identity.

Session refresh

RefreshSessionToken

  • Used exclusively to refresh an existing session.
  • Requires a valid long-lived opaque refresh session token.
  • Issues a new JWT access token.
  • Invalidates and destroys any previously issued access tokens associated with the refreshed session.
  • May rotate the refresh token according to server policy.

This endpoint always returns a newly issued JWT representing the authenticated subject (user or service), regardless of the authentication mechanism used.

Authorizations:
(BasicAuthSolutionID) (X-API-KeySolutionID) RefreshSessionToken
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Create session persons
# Authenticate user using email and password.
# BasicAuth + SolutionID
curl -X POST 'https://{{url}}/sessions' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Basic your_base64_credentials' \
  -H 'solutionID: your_api_key_here' \

#--------------------

# Create session B2B
# Authenticate service using API Key.
# X-API-Key + SolutionID
curl -X POST 'https://{{url}}/sessions' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: X-API-Key your_api_key_here' \
  -H 'solutionID: your_api_key_here' \

#--------------------

# Refresh session
# Obtain new access token using refresh token.
# RefreshSessionToken
curl -X POST 'https://{{url}}/sessions' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "refreshToken": "mF_9.B5f-4.1JqM"
}

Delete session

Invalidates the current session or access token.

  • BearerAuth (JWT): Invalidates the user session.
  • X-API-Key (B2B): Revokes the service access token.

OAuth note: This operation is equivalent to OAuth 2.0 Token Revocation (RFC 7009).

Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/sessions' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

Request MFA code for password change

Generates a temporary Multi-Factor Authentication (MFA) code to authorize a password change request. This code must be provided to PUT /entity/password to complete the operation.

Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/entity/password' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

Change password

Updates the authenticated entity's password. Requires a valid MFA code generated via GET /entity/password if Multi-Factor Authentication is enabled.

Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
One of
newPassword
required
string (New Password)

The new password for the person.

Responses

Request samples

Content type
application/json
Example
{
  • "newPassword": "newPassword123"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get MFA code to recover password

Generates a temporary MFA code to authenticate password recovery requests. This code is required by PUT /entity/recovery to validate and complete the reset.

Authorizations:
(BasicAuthWithoutPasswordSolutionID)
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Password recovery
# Initiate password recovery flow.
# BasicAuthWithoutPassword + SolutionID
curl -X GET 'https://{{url}}/entity/recovery' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Basic your_base64_credentials' \
  -H 'solutionID: your_api_key_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

Recover the password

Completes the password recovery process using a valid MFA code generated by GET /entity/recovery.

Authorizations:
(BasicAuthWithoutPasswordSolutionID)
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
One of
newPassword
required
string (New Password)

The new password for the person.

Responses

Request samples

Content type
application/json
Example
{
  • "newPassword": "newPassword123"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

List access tokens

Retrieves a list of all active access tokens associated with the authenticated entity.

permissions: ["one_access_#r"]
Authorizations:
BearerAuth

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/tokens' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "f81d4fae-7dec-11d0-a765-00a0c91e6bf6": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "2c1a9c4e-91f4-4e3b-9c2a-8d9e4b2f1a77": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Create a new access token

Creates a single access token scoped to one solution identifier.

This endpoint follows a one-to-one model:

  • One request → one identifier
  • One identifier → one access token
  • One access token → one solution

Bulk or multi-solution token creation is not supported. To obtain tokens for multiple solutions, this endpoint must be called once per solution identifier.

The issued token grants authorization only to the specified solution and MUST be used as a Bearer token when accessing solution-scoped resources.

permissions: ["one_access_#c"]
Authorizations:
BearerAuth
Request Body schema: application/json
required
identifier
required
string <uuid>

Unique identifier of the solution for which the access token will be issued.

The resulting access token grants authorization only to this solution and cannot be reused for other identifiers.

Responses

Request samples

Content type
application/json
{
  • "identifier": "f81d4fae-7dec-11d0-a765-00a0c91e6bf7"
}

Response samples

Content type
application/json
{
  • "f81d4fae-7dec-11d0-a765-00a0c91e6bf6": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "2c1a9c4e-91f4-4e3b-9c2a-8d9e4b2f1a77": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Get access token

Retrieves the access token for a specific solution identifier. Returns exactly one entry matching the requested ID.

permissions: ["one_access_#r"]
Authorizations:
BearerAuth
path Parameters
UUID
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Identifier of solutions of access token to view.

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/tokens/{UUID}' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "2c1a9c4e-91f4-4e3b-9c2a-8d9e4b2f1a77": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXFCE9..."
}

Delete access token

Revokes the access token associated with the specified identifier.

permissions: ["one_access_#d"]
Authorizations:
BearerAuth
path Parameters
UUID
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Identifier of solutions of access token to view.

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/tokens/{UUID}' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

Refresh access token

Endpoint to refresh the access token

permissions: ["one_access_#u"]
Authorizations:
BearerAuth
path Parameters
UUID
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Identifier of solutions of access token to view.

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X POST 'https://{{url}}/tokens/{UUID}' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "f81d4fae-7dec-11d0-a765-00a0c91e6bf6": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "2c1a9c4e-91f4-4e3b-9c2a-8d9e4b2f1a77": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Person entity

Endpoints related to entity administration and delegation.

An ENTITY is the primary subject of authorization. It operates within explicitly defined scopes resolved through relationships

An entity:

  • holds exactly one role
  • activates permissions defined by that role
  • operates within scopes resolved through explicit relationships
  • may administer scoped resources if explicitly permitted
  • may create and manage child entities (collaborators), if explicitly authorized

Resource: ENTITY

An ENTITY operates within explicitly defined scopes and relationships.

Parent–Collaborator Delegation Model

Entities utilize the Collaborator Pattern for safe delegation:

  • A Parent Entity defines the maximum permission universe and operational scope for its children.
  • A Collaborator (Child Entity) activates a strict subset of the parent's permissions and operates within a delegated boundary.
  • This model prevents privilege escalation by ensuring parents limit, never amplify authority.

Collaborator Pattern

A collaborator is a business-level term representing a child entity created under a parent entity for delegated administration.

A collaborator:

  • is created with the same role as its parent
  • activates a strict subset of the parent entity’s active permissions
  • operates within a delegated and bounded scope

This pattern enables safe delegation of administrative responsibilities (e.g. billing, device management, user support) without introducing role inheritance or implicit privilege escalation.

Read all visible persons

Retrieves a comprehensive list of all persons visible to the authenticated entity.

The scope of the returned list depends on the authenticated entity's role and permissions. This provides a complete overview of all associated persons within the administrative domain.

permission: ["one_persons_#r"]
Authorizations:
BearerAuth
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/persons' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    }
]

Read a person's information

Retrieves the profile information for a single person.

permission: ["one_persons_#r"]
Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/persons/{PERSON}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "id": "65b55214a9bf015dc703bcf9",
  • "parentID": "65b55214a9bf015dc703bcf9",
  • "status": "activate",
  • "role": "account",
  • "firstname": "John",
  • "lastname": "Doe",
  • "email": "user@example.com",
  • "phonenumber": "+11111111111",
  • "birthday": "1990-01-01",
  • "permissions": "one_solution_read",
  • "createTimestamp": "2024-01-24T12:00:00Z",
  • "lastActivityTimestamp": "2024-01-24T12:00:00Z"
}

Update a person's information

"Modifies the profile information of a specific person.

An entity can only modify other persons' information if they have the appropriate administrative permissions."

permission: ["one_persons_#u"]
Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
email
required
string

Person's email address.

firstname
required
string

Person's first name.

lastname
required
string

Person's last name.

parentID
required
string <uuid>

Identifier of the parent entity creating this person. When provided, the created person becomes a collaborator of the parent entity. The parent defines the maximum permissions and operational scope that the new entity may activate. No permissions are inherited implicitly.

permissions
required
string (Permissions) ^(one|os|sd)_(entity|session|account|solution...

Defines the technical model used to structure Permissions within the SpectreGrid ecosystem, provided as a comma-separated string.

Permissions determine which actions an entity is allowed to perform, both at the API level and within the user interface.

Each permission follows the format:

<solution>_<object>_<permission>

Where:

  • <solution> ∈ {one, os, sd}
  • <object> and <permission> are lowercase snake_case identifiers.
  • Optional parameters can be added in parentheses, e.g. one_zone_force(zone-uuid).

The permission are case insensitive.

phonenumber
required
string

Person's phone number.

birthDay
required
string <date>

Person's birth date in YYYY-MM-DD format.

Responses

Request samples

Content type
application/json
{
  • "email": "person@example.com",
  • "firstname": "John",
  • "lastname": "Doe",
  • "parentID": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  • "permissions": "one_persons_#c, one_devices_assing(f81d4fae-7dec-11d0-a765-00a0c91e6bf6)",
  • "phonenumber": "+549123456789",
  • "birthDay": "1990-01-01"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Delete a person

Deletes a specific person from the system.

Warning: This operation is irreversible and is restricted to entities with administrative permissions.

permission: ["one_persons_#d"]
Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/persons/{PERSON}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

Send person activation code

Sends an MFA code to the person's registered communication channel. This code is required by PUT /persons/activation to complete the process.

Authorizations:
(BasicAuthWithoutPasswordSolutionID)

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Password recovery
# Initiate password recovery flow.
# BasicAuthWithoutPassword + SolutionID
curl -X GET 'https://{{url}}/persons/activation' \
  -H 'Authorization: Basic your_base64_credentials' \
  -H 'solutionID: your_api_key_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

Activate person.

Activates a person using the provided activation code sent via GET /persons/activation.

Authorizations:
(BasicAuthWithoutPasswordSolutionID)
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
email
required
string

entity email

codeAuth
required
string

Authorization code of entity

Responses

Request samples

Content type
application/json
{
  • "email": "entity@example.com",
  • "codeAuth": "152157"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

[BATCH] Delete persons

Deletes multiple persons in a single batch operation.

This endpoint permanently deletes persons identified by a list of UUIDs in the request body. This operation is irreversible.

permission: ["one_persons_#d"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
required
Array of strings or (MUID (string) or MUID (string))

List of resource identifiers to delete. The identifier type (UUID or MUID) depends on the specific resource.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "OK"
}

Read all solutions associated with a person

Retrieves a list of all solutions associated with a specific person.

permission: ["one_solution_#r"]
Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/persons/{PERSON}/solutions' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    }
]

Create a new solution for a person

Registers a new solution associated with the person {PERSON}.

permission: ["one_solution_allocate"]
Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Request Body schema: application/json
required
name
string

Name of the solution

solutionTemplateID
string <UUID>

The unique identifier for the solution template.

Responses

Request samples

Content type
application/json
{
  • "name": "SpectreONE-A",
  • "solutionTemplateID": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "status": "error",
  • "message": "Bad Request"
}

Transfer a solution to a person

Transfers ownership of an existing solution to the person {PERSON}.

permission: ["one_solution_transfer"]
Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Request Body schema: application/json
required
solutionId
required
string <uuid>

Identifier of the solution to transfer

Responses

Request samples

Content type
application/json
{
  • "solutionId": "9ff66092-33fb-498c-8123-e85aa68facfe"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Read a person's collaborators

Retrieves a list of collaborators for a specified parent person.

This endpoint returns the direct collaborators of a given person.

Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/persons/{PERSON}/collaborators' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    }
]

Read all unassigned devices for a person

Retrieves a list of all devices that are owned by a specific person but are not yet assigned to a solution.

permission: ["one_devices_#r"]
Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/persons/{PERSON}/devices' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Transfer unassigned devices to a person

Transfers one or more unassigned devices to the specified person.

permission: ["one_devices_transfer"]
Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Request Body schema: application/json
required
Array of MUID (string) or MUID (string) (MUID)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "OK"
}

Delete all devices from a person

Deletes all devices associated with the specified person.

Warning: This operation is irreversible and will permanently remove all devices owned by the person.

permission: ["one_devices_#d"]
Authorizations:
BearerAuth
path Parameters
PERSON
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of person, can be replaced by "me" alias in the path of request to reference the person that makes the request.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/persons/{PERSON}/devices' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

Solutions

Endpoints related to solution provisioning and administration.

Solutions are provisioned and administered by entities operating under appropriate roles and permissions.

These endpoints provide capabilities to configure, monitor, and control solution-level resources.

Resource: SOLUTION TEMPLATE

A SOLUTION TEMPLATE defines a predefined set of services, capabilities, and supported device types.

It acts as a blueprint from which concrete solutions are provisioned.

Resource: SOLUTION

A SOLUTION is a deployed instance of a solution template, administered by one or more entities within explicitly defined scopes.

A solution contains:

  • Zones of permissions (ZONE)
  • Devices (DEVICE)
  • End-user accounts (USER)

Solutions represent active, contracted service deployments.

Read all visible solutions

Retrieves a list of all solutions the authenticated entity is authorized to see. The scope of the data returned depends on the requester's permissions.

permission: ["one_solution_#r"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/solutions' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    }
]

Create a new solution

Provisions a new solution from a specified solution template. This operation is restricted to entities with the appropriate permissions.

permission: ["one_template_allocate"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Request Body schema: application/json
required
name
string

Name of the solution

solutionTemplateID
string <UUID>

The unique identifier for the solution template.

Responses

Request samples

Content type
application/json
{
  • "name": "SpectreONE-A",
  • "solutionTemplateID": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Update a solution

Modifies an existing solution. The 'UUID' of the solution must be provided in the request body. This action requires appropriate update permissions.

permission: ["one_solution_#u"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

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

Unique identifier with format uuid

type
string
Enum: "identity" "solution"

Type of solutions. A "identity" solution is a solution that provide identity services. A "solution" is a solution that provide other services, like iot devices access. A solution type solution consume a identity solotuin to identify sessions ans permissions

level
string
Enum: "primary" "secondary"

Level of the solution. The level inidicate if is primary level of "identity" or secundary level of "identity". The primary level is the main solution used in the ecosystem. The secundary level is a soltion of type "identity" created in a primary level solution.

name
required
string

Name of the solution

templateID
required
string <UUID>

The unique identifier for the solution template.

status
required
string
Enum: "enable" "disable" "paused" "run"

Status of solution.

createTimestamp
required
string <date-time>

Date of creation

Responses

Request samples

Content type
application/json
{
  • "uuid": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  • "type": "identity",
  • "level": "primary",
  • "name": "SpectreONE-A",
  • "templateID": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "run",
  • "createTimestamp": "2024-11-20T14:30:00Z"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Read solution information

Retrieves detailed information and metadata for the specified solution.

permission: ["one_solution_#r"]
Authorizations:
BearerAuth
path Parameters
SOLUTION
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of a solution.

This parameter accepts either:

  • a solution UUID
  • a reserved alias, depending on the endpoint.

Supported aliases

  • my
    Resolves to the solution that owns the credentials used in the request
    (i.e. the solution acting as the caller).

    When used, the request is scoped to the caller solution only.

  • one (restricted)
    Resolves to the single solution in which the authenticated entity is currently operating.

    This alias is only permitted for the following endpoints. Its usage on any other endpoint WILL be rejected.

    GET /solutions/{SOLUTION}/persons
POST /solutions/{SOLUTION}/persons

    When one is used:

    • the API resolves the target solution as SpectreONE, based on the authenticated entity context
    • when used with POST /solutions/{SOLUTION}/persons, the person being created MUST NOT have the user role
    • violations of the rules above result in a 400 Bad Request response
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/solutions/{SOLUTION}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "uuid": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  • "type": "identity",
  • "level": "primary",
  • "name": "SpectreONE-A",
  • "templateID": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "run",
  • "createTimestamp": "2024-11-20T14:30:00Z"
}

Delete a solution

Removes a specific solution from the system.

permission: ["one_solution_#d"]
Authorizations:
BearerAuth
path Parameters
SOLUTION
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of a solution.

This parameter accepts either:

  • a solution UUID
  • a reserved alias, depending on the endpoint.

Supported aliases

  • my
    Resolves to the solution that owns the credentials used in the request
    (i.e. the solution acting as the caller).

    When used, the request is scoped to the caller solution only.

  • one (restricted)
    Resolves to the single solution in which the authenticated entity is currently operating.

    This alias is only permitted for the following endpoints. Its usage on any other endpoint WILL be rejected.

    GET /solutions/{SOLUTION}/persons
POST /solutions/{SOLUTION}/persons

    When one is used:

    • the API resolves the target solution as SpectreONE, based on the authenticated entity context
    • when used with POST /solutions/{SOLUTION}/persons, the person being created MUST NOT have the user role
    • violations of the rules above result in a 400 Bad Request response
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/solutions/{SOLUTION}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

[BATCH] Delete listed solutions

Deletes a list of solutions identified by their UUIDs in the request body. This is a batch operation and is irreversible. Ensure that the list of UUIDs is correct before executing this request, as deleting a solution may affect associated entities.

permission: ["one_solution_#d"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
required
Array of strings or (MUID (string) or MUID (string))

List of resource identifiers to delete. The identifier type (UUID or MUID) depends on the specific resource.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "OK"
}

Read persons by solution

Retrieves a list of persons associated with the specified solution context. Results can be filtered by role.

permission: ["one_persons_#r"]
Authorizations:
BearerAuth
path Parameters
SOLUTION
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of a solution.

This parameter accepts either:

  • a solution UUID
  • a reserved alias, depending on the endpoint.

Supported aliases

  • my
    Resolves to the solution that owns the credentials used in the request
    (i.e. the solution acting as the caller).

    When used, the request is scoped to the caller solution only.

  • one (restricted)
    Resolves to the single solution in which the authenticated entity is currently operating.

    This alias is only permitted for the following endpoints. Its usage on any other endpoint WILL be rejected.

    GET /solutions/{SOLUTION}/persons
POST /solutions/{SOLUTION}/persons

    When one is used:

    • the API resolves the target solution as SpectreONE, based on the authenticated entity context
    • when used with POST /solutions/{SOLUTION}/persons, the person being created MUST NOT have the user role
    • violations of the rules above result in a 400 Bad Request response
query Parameters
Account (string) or Manager (string) or User (string)

Filter persons by role.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/solutions/{SOLUTION}/persons' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    }
]

[BATCH] Register a new person.

This endpoint registers a one or more new person in the system with their personal information.

Input formats supported:

Content-Type Description
application/json Single user object or an array of user objects for batch creation.
multipart/form-data A compressed file (ZIP, GZIP, TAR, 7Z, etc.) containing batch data, plus metadata fields.

JSON input

You can send either:

  • A single JSON object that matches the UserCreation schema, or
  • A JSON array of such objects for bulk creation.

Multipart input

When using multipart/form-data, the following parts must be included:

  • file → the compressed file containing the batch data.
  • format → defines the type of data inside the compressed file (csv or json).
  • defaults → (optional) JSON object providing default values for missing or empty fields in each record.

CSV file rules

  • The CSV file must include a header row.
  • The header names must exactly match with:
    • firstName
    • lastName
    • email
    • password
    • phoneNumber
    • birthDay
    • role
  • Each subsequent row represents one user record.
  • Empty fields will be replaced by corresponding values defined in defaults, if provided.

JSON file rules

  • The compressed file must contain a single JSON array of objects matching the UserCreation schema.

Compression

Supported compression formats are: zip, gzip, tar, 7z.

Alias and role constraints

When this endpoint is invoked using the path alias one:

  • Creation is allowed only if the requested role is user.
  • The created person is automatically associated with the solution resolved by the one alias.
  • No parent or cross-solution delegation is permitted.

If the alias one is used with any role other than user,
the server MUST reject the request with 400 Bad Request.

permission: ["one_persons_register"]
Authorizations:
BearerAuth
path Parameters
SOLUTION
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of a solution.

This parameter accepts either:

  • a solution UUID
  • a reserved alias, depending on the endpoint.

Supported aliases

  • my
    Resolves to the solution that owns the credentials used in the request
    (i.e. the solution acting as the caller).

    When used, the request is scoped to the caller solution only.

  • one (restricted)
    Resolves to the single solution in which the authenticated entity is currently operating.

    This alias is only permitted for the following endpoints. Its usage on any other endpoint WILL be rejected.

    GET /solutions/{SOLUTION}/persons
POST /solutions/{SOLUTION}/persons

    When one is used:

    • the API resolves the target solution as SpectreONE, based on the authenticated entity context
    • when used with POST /solutions/{SOLUTION}/persons, the person being created MUST NOT have the user role
    • violations of the rules above result in a 400 Bad Request response
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema:
required
email
required
string

Person's email address.

firstname
required
string

Person's first name.

lastname
required
string

Person's last name.

parentID
string <uuid>

Identifier of the parent entity creating this person. When provided, the created person becomes a collaborator of the parent entity. The parent defines the maximum permissions and operational scope that the new entity may activate. No permissions are inherited implicitly.

required
Account (string) or Manager (string) or User (string)

Indicate the role of the person to create.

password
required
string

Person's password, which will be encrypted before transmission.

phonenumber
required
string

Person's phone number.

birthDay
required
string <date>

Person's birth date in YYYY-MM-DD format.

Responses

Request samples

Content type
{
  • "email": "person@example.com",
  • "firstname": "John",
  • "lastname": "Doe",
  • "parentID": "65b55214a9bf015dc703bcf9",
  • "role": "account",
  • "password": "password123",
  • "phonenumber": "+549123456789",
  • "birthDay": "1990-01-01"
}

Response samples

Content type
application/json
[
  • "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  • "f81d4fae-7dec-11d0-a765-00a0c91e6bf5"
]

Read solution devices

Retrieves a list of all devices associated with the specified solution.

permission: ["one_devices_#r"]
Authorizations:
BearerAuth
path Parameters
SOLUTION
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of a solution.

This parameter accepts either:

  • a solution UUID
  • a reserved alias, depending on the endpoint.

Supported aliases

  • my
    Resolves to the solution that owns the credentials used in the request
    (i.e. the solution acting as the caller).

    When used, the request is scoped to the caller solution only.

  • one (restricted)
    Resolves to the single solution in which the authenticated entity is currently operating.

    This alias is only permitted for the following endpoints. Its usage on any other endpoint WILL be rejected.

    GET /solutions/{SOLUTION}/persons
POST /solutions/{SOLUTION}/persons

    When one is used:

    • the API resolves the target solution as SpectreONE, based on the authenticated entity context
    • when used with POST /solutions/{SOLUTION}/persons, the person being created MUST NOT have the user role
    • violations of the rules above result in a 400 Bad Request response
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/solutions/{SOLUTION}/devices' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Assign devices to a solution

Allocates one or more unassigned devices to the specified solution.

permission: ["one_devices_assign"]
Authorizations:
BearerAuth
path Parameters
SOLUTION
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of a solution.

This parameter accepts either:

  • a solution UUID
  • a reserved alias, depending on the endpoint.

Supported aliases

  • my
    Resolves to the solution that owns the credentials used in the request
    (i.e. the solution acting as the caller).

    When used, the request is scoped to the caller solution only.

  • one (restricted)
    Resolves to the single solution in which the authenticated entity is currently operating.

    This alias is only permitted for the following endpoints. Its usage on any other endpoint WILL be rejected.

    GET /solutions/{SOLUTION}/persons
POST /solutions/{SOLUTION}/persons

    When one is used:

    • the API resolves the target solution as SpectreONE, based on the authenticated entity context
    • when used with POST /solutions/{SOLUTION}/persons, the person being created MUST NOT have the user role
    • violations of the rules above result in a 400 Bad Request response
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Request Body schema: application/json
required
Array of MUID (string) or MUID (string) (MUID)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "OK"
}

Retrieve zones

Returns a list of zones associated with the given solution.

permission: ["one_zones_#r"]
Authorizations:
BearerAuth
path Parameters
SOLUTION
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of a solution.

This parameter accepts either:

  • a solution UUID
  • a reserved alias, depending on the endpoint.

Supported aliases

  • my
    Resolves to the solution that owns the credentials used in the request
    (i.e. the solution acting as the caller).

    When used, the request is scoped to the caller solution only.

  • one (restricted)
    Resolves to the single solution in which the authenticated entity is currently operating.

    This alias is only permitted for the following endpoints. Its usage on any other endpoint WILL be rejected.

    GET /solutions/{SOLUTION}/persons
POST /solutions/{SOLUTION}/persons

    When one is used:

    • the API resolves the target solution as SpectreONE, based on the authenticated entity context
    • when used with POST /solutions/{SOLUTION}/persons, the person being created MUST NOT have the user role
    • violations of the rules above result in a 400 Bad Request response
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/solutions/{SOLUTION}/zones' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    }
]

[BATCH] Create one or more zones.

Creates new zones associated with the given solution.

Input formats supported:

Content-Type Description
application/json Single zone object or an array of zone objects for batch creation.
multipart/form-data A compressed file (ZIP, GZIP, TAR, 7Z, etc.) containing batch data, plus metadata fields.

JSON input

You can send either:

  • A single JSON object that matches the ZoneCreate schema, or
  • A JSON array of such objects for bulk creation.

Multipart input

When using multipart/form-data, the following parts must be included:

  • file → the compressed file containing the batch data.
  • format → defines the type of data inside the compressed file (csv or json).
  • defaults → (optional) JSON object providing default values for missing or empty fields in each record.

CSV file rules

  • The CSV file must include a header row.
  • The header names must exactly match with the fields defined in ZoneCreate.
  • The columns must follow the same order as in the schema definition.
  • Each subsequent row represents one zone record.
  • Empty fields will be replaced by corresponding values defined in defaults, if provided.

JSON file rules

  • The compressed file must contain a single JSON array of objects matching the ZoneCreate schema.

Compression

Supported compression formats are: zip, gzip, tar, 7z.

permission: ["one_zones_#c"]
Authorizations:
BearerAuth
path Parameters
SOLUTION
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of a solution.

This parameter accepts either:

  • a solution UUID
  • a reserved alias, depending on the endpoint.

Supported aliases

  • my
    Resolves to the solution that owns the credentials used in the request
    (i.e. the solution acting as the caller).

    When used, the request is scoped to the caller solution only.

  • one (restricted)
    Resolves to the single solution in which the authenticated entity is currently operating.

    This alias is only permitted for the following endpoints. Its usage on any other endpoint WILL be rejected.

    GET /solutions/{SOLUTION}/persons
POST /solutions/{SOLUTION}/persons

    When one is used:

    • the API resolves the target solution as SpectreONE, based on the authenticated entity context
    • when used with POST /solutions/{SOLUTION}/persons, the person being created MUST NOT have the user role
    • violations of the rules above result in a 400 Bad Request response
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema:
required
One of
@type
required
string
Enum: "polygon" "circle"
name
required
string

The name of the zone.

required
Array of objects (Polygon) >= 3 items

A polygon defined by a list of geographical positions. The first and last positions are assumed to be connected.

Responses

Request samples

Content type
Example
{
  • "name": "Zone name",
  • "@type": "polygon",
  • "body": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Delete zones

Deletes all zones associated with the specified solution pair.

Warning:
The full deletion operation is irreversible. Use with caution.

permission: ["one_zones_#d"]
Authorizations:
BearerAuth
path Parameters
SOLUTION
required
string <uuid>
Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Unique identifier of a solution.

This parameter accepts either:

  • a solution UUID
  • a reserved alias, depending on the endpoint.

Supported aliases

  • my
    Resolves to the solution that owns the credentials used in the request
    (i.e. the solution acting as the caller).

    When used, the request is scoped to the caller solution only.

  • one (restricted)
    Resolves to the single solution in which the authenticated entity is currently operating.

    This alias is only permitted for the following endpoints. Its usage on any other endpoint WILL be rejected.

    GET /solutions/{SOLUTION}/persons
POST /solutions/{SOLUTION}/persons

    When one is used:

    • the API resolves the target solution as SpectreONE, based on the authenticated entity context
    • when used with POST /solutions/{SOLUTION}/persons, the person being created MUST NOT have the user role
    • violations of the rules above result in a 400 Bad Request response
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/solutions/{SOLUTION}/zones' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

List solution templates

Retrieves a list of all available solution templates. The visibility of these templates may be restricted based on the authenticated entity's permissions.

permission: ["one_template_#r"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/templates' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    }
]

Create a new solution template

Creates a new solution template that can be used to instantiate new solutions. This operation is restricted to entities with administrative privileges.

permission: ["one_template_#c"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
name
required
string

Name of the solution.

shortName
required
string

Short name of the solution.

version
required
string^[1-9]\.[1-9]\.[1-9]$

Version of the solution template.

Responses

Request samples

Content type
application/json
{
  • "name": "SpectreONE",
  • "shortName": "os",
  • "version": "1.1.1"
}

Response samples

Content type
application/json
{
  • "templateID": "123e4567-e89b-12d3-a456-426614174000"
}

Delete all solution templates

Deletes all existing solution templates from the system. This is a bulk, irreversible operation and should be used with extreme caution as it may affect the ability to create new solutions.

permission: ["one_template_#d"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/templates' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "status": "error",
  • "message": "Bad Request"
}

Get a solution template

Retrieves a specific solution template by its identifier.

permission: ["one_template_#r"]
Authorizations:
BearerAuth
path Parameters
TEMPLATE
required
string <UUID>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier for the solution template.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/templates/{TEMPLATE}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "templateID": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "SpectreONE",
  • "shortName": "os",
  • "version": "1.1.1"
}

Delete a solution template

Removes a specific solution template from the system.

permission: ["one_template_#d"]
Authorizations:
BearerAuth
path Parameters
TEMPLATE
required
string <UUID>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier for the solution template.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/templates/{TEMPLATE}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "status": "error",
  • "message": "Bad Request"
}

Update a solution template

Updates the properties of a specific solution template.

permission: ["one_template_#u"]
Authorizations:
BearerAuth
path Parameters
TEMPLATE
required
string <UUID>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier for the solution template.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
name
required
string

Name of the solution.

shortName
required
string

Short name of the solution.

version
required
string^[1-9]\.[1-9]\.[1-9]$

Version of the solution template.

Responses

Request samples

Content type
application/json
{
  • "name": "SpectreONE",
  • "shortName": "os",
  • "version": "1.1.1"
}

Response samples

Content type
application/json
{
  • "status": "error",
  • "message": "Bad Request"
}

Zones of permissions

Endpoints for managing geographical boundaries (ZONES) within a solution.

Zones serve as the final layer of permission resolution. In this model, permissions are not static; they are resolved according to the zone where a device is located.

Resource: GLOBAL ZONE

A reserved zone (GLOBAL) that provides unrestricted access, overriding geographical constraints for universal policies across a solution.

The identifier GLOBAL is reserved for use in:

  • Zone names
  • Permission scopes
  • Access policies that must apply universally across the solution

Zone Capabilities

Zones may be:

  • Created or removed
  • Updated to modify boundaries or shapes
  • Configured with specific access rules and constraints

Retrieve all visible zones

Retrieves a list of all zones the authenticated entity has visibility over.

permission: ["one_zones_#r"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/zones' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    }
]

Delete all zones for a solution

Deletes all zones associated with the solution context of the request.

Warning: This operation is irreversible.

permission: ["one_zones_#d"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/zones' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

Retrieve a specific zone

Retrieves the information for a single zone, identified by its UUID.

permission: ["one_zones_#r"]
Authorizations:
BearerAuth
path Parameters
ZONE
required
string <uuid>

The UUID of the zone.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/zones/{ZONE}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
Example
{
  • "@type": "polygon",
  • "identifier": "d942f9d8-e783-4e83-aa27-10a4823d8d85",
  • "name": "Zone name",
  • "body": [
    ]
}

Modify an existing zone

Updates an existing zone.

permission: ["one_zones_#u"]
Authorizations:
BearerAuth
path Parameters
ZONE
required
string <uuid>

The UUID of the zone.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
One of
@type
required
string
Enum: "polygon" "circle"
name
string

The name of the zone.

required
Array of objects (Polygon) >= 3 items

A polygon defined by a list of geographical positions. The first and last positions are assumed to be connected.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Zone name",
  • "@type": "polygon",
  • "body": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "@type": "polygon",
  • "body": [
    ]
}

Delete a specific zone

Permanently deletes a zone from the system. This operation is irreversible.

permission: ["one_zones_#d"]
Authorizations:
BearerAuth
path Parameters
ZONE
required
string <uuid>

The UUID of the zone.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/zones/{ZONE}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "status": "error",
  • "message": "Bad Request"
}

[BATCH] Delete a list of zones

Deletes multiple zones in a single batch operation.

Warning: The full deletion operation is irreversible. Use with caution.

permission: ["one_zones_#d"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Request Body schema: application/json
required
required
Array of strings or (MUID (string) or MUID (string))

List of resource identifiers to delete. The identifier type (UUID or MUID) depends on the specific resource.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "OK"
}

Read all devices in a zone

Retrieves a list of all devices located within a specific zone.

permission: ["one_devices_#r"]
Authorizations:
BearerAuth
path Parameters
ZONE
required
string <uuid>

The UUID of the zone.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/zones/{ZONE}/devices' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Locate devices within a zone

Locate one or more devices to the specified geographical zone.

permission: ["one_devices_locate"]
Authorizations:
BearerAuth
path Parameters
ZONE
required
string <uuid>

The UUID of the zone.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Request Body schema: application/json
required
Array of MUID (string) or MUID (string) (MUID)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "OK"
}

Devices

Endpoints for managing devices (DEVICE) and their lifecycle through the transfer model.

This section provides APIs for device registration, inspection, and lifecycle management within a solution.

In SpectreGRID, devices form a hierarchical, tree-like structure with strict parent–child constraints.

Device Hierarchy

The currently supported device hierarchy is:

  • Gateways are root nodes
  • End-Devices are leaf nodes

Valid relationships:

  • Gateway → End-Device

Invalid relationships (not allowed):

  • Gateway → Gateway
  • End-Device → Gateway
  • End-Device → End-Device

Device Types

Gateway

A Gateway is a root-level device responsible for managing one or more End-Devices.

Characteristics:

  • Provides network connection
  • May include GPS capabilities
  • Acts as the aggregation and control point for End-Devices

End-Device

An End-Device is a leaf node in the device hierarchy.

Characteristics:

  • Connects directly to a Gateway
  • Performs specific operational or sensing functions
  • Is the primary unit being monitored or controlled

Capabilities by Device Type

Device Type Capabilities
Gateway - Manages multiple End-Devices
- Monitored for connection and GPS status
End-Device - Connects to a Gateway
- Monitored for operational state and connection

Reference Diagram

The following diagram illustrates the supported device connection model:

SpectreGRID Device Connection Diagram

Read all unassigned devices

Retrieves a list of all unassigned devices. The visibility of these resources depends on the permissions of the authenticated entity.

permission: ["one_devices_#r"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/devices' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Remove all unassigned devices

Deletes all devices that are currently unassigned.

Warning: This is a bulk operation and is irreversible. Use with extreme caution.

permission: ["one_devices_#d"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/devices' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

Read device information

Retrieves detailed information and metadata for a specific device.

permission: ["one_devices_#r"]
Authorizations:
BearerAuth
path Parameters
required
MUID (string) or MUID (string) (MUID)
Example: 65b55214a9bf015dc703bcf9
canonical-name: MUID

MUID of the device. The device object can be a gateway or position or station.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X GET 'https://{{url}}/devices/{MUID}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
Example
{
  • "@type": "gateway",
  • "id": "65b55214a9bf015dc703bcf9",
  • "name": "Gateway 1",
  • "active": "n",
  • "version": {
    },
  • "channel": "cellular",
  • "geoLocation": {
    },
  • "createTimestamp": "2024-01-24T12:00:00Z"
}

Delete a device

Removes a specific device from the system.

permission: ["one_devices_#d"]
Authorizations:
BearerAuth
path Parameters
required
MUID (string) or MUID (string) (MUID)
Example: 65b55214a9bf015dc703bcf9
canonical-name: MUID

MUID of the device. The device object can be a gateway or position or station.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Responses

Request samples 

# !!! WARNING: CODE VALID UNTIL {{ expiration_date }} !!!
# Access protected resources
# Use a valid JWT obtained after create sessions.
# BearerAuth
curl -X DELETE 'https://{{url}}/devices/{MUID}' \
  -H 'API-Version: 1.1.1' \
  -H 'Authorization: Bearer your_jwt_token_here' \

Response samples

Content type
application/json
{
  • "message": "OK"
}

[BATCH] Modify devices

This endpoint allows managing a parent–child relationship for devices using the device MUID provided in the path as the parent.

Depending on the request body, the endpoint supports the following operations:

  • Link one or more existing devices as children of the parent device by providing a list of device MUIDs.
  • Update the parent device data by providing a full Device object.

The request body must conform to exactly one of the supported schemas.

permission: ["one_devices_#u"]
Authorizations:
BearerAuth
path Parameters
required
MUID (string) or MUID (string) (MUID)
Example: 65b55214a9bf015dc703bcf9
canonical-name: MUID

MUID of the device. The device object can be a gateway or position or station.

header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Request Body schema: application/json
required
One of
Array of MUID (string) or MUID (string) (List of id devices)

An array of Device objects to link to the parent device.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "OK"
}

Delete listed unassigned devices

Deletes listed unassigned devices.

Warning:
The deletion operation is irreversible. Use with caution.

permission: ["one_devices_#d"]
Authorizations:
BearerAuth
header Parameters
API-Version
string^([0-9]+)\.([0-9]+)\.([0-9]+)$
Example: 1.1.1

Version of the API requested by the client, in semantic version format.

  • major: breaking changes
  • minor: backwards-compatible changes
  • patch: fixes with no contract impact

If omitted, the server will respond using the latest stable API version.

"^([0-9]+)\\.([0-9]+)\\.([0-9]+)$"
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT token used to authenticate the request

Request Body schema: application/json
required
required
Array of (MUID (string) or MUID (string)) or ((MUID (MUID (string) or MUID (string))) or (MUID (MUID (string) or MUID (string))))

List of resource identifiers to delete. The identifier type (UUID or MUID) depends on the specific resource.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "OK"
}