Web SDK Partitions

Working with Partitions

Overview

A partition in Security Center is an entity that controls which parts of the system are visible to which users. It acts as a container that groups entities, and only users who are authorized for that partition can see the entities it contains. If a user has no rights to a partition, the partition and everything inside it is hidden from that user.

A partition contains two main elements:

1. Members - The entities that belong to the partition (areas, doors, cameras, cardholders, users, etc.)
2. Authorized users and groups - Users who can see and work with those entities based on their privileges

Why use partitions?

Partitions break a system into smaller, independent sections. This reduces what each user can access and improves both security and usability, especially in multi-site environments where one team should not see another team's operations.

Common use cases:

• Multi-tenant systems where each organization sees only their own entities
• Geographic separation (building, campus, region)
• Departmental access control (HR, Security, Operations)
• Hierarchical security models with parent-child partition relationships

Key concepts:

• Entities belong to one or more partitions
• Users must have access to a partition to see its entities
• New entities are created in default partition(s) unless otherwise specified
• Partitions can be nested in a hierarchy for inheritance

Understanding Default Partitions

When you log in to the Web SDK, your session has default creation partitions. These determine where new entities are created unless you explicitly specify otherwise.

CRITICAL FOR SAAS ENVIRONMENTS:

In Security Center SaaS (Classic) and partition-isolated deployments, users typically do NOT have access to the root partition. In these environments, you MUST call /creationpartition once per session before creating entities, otherwise entity creation will fail with a privilege error.

Without calling /creationpartition:

• Entity creation attempts will fail
• Error: "Logged-on user does not have sufficient privileges"
• The system tries to create in the root partition (which the user cannot access)

Session behavior:

• The setting is stored in your Web SDK session
• Sessions are identified by username + Application ID
• All requests with the same credentials share the same session
• Sessions expire after 5 minutes of inactivity
• When a session expires, the /creationpartition setting is lost

Recommended approach:

Since there is no way for clients to detect session expiration, use one of these strategies:

1. Startup + Keep-Alive (Recommended):

   • Call /creationpartition when your application starts
   • Implement session keep-alive (send a request every 4 minutes)
   • The partition setting will never be lost

2. Always Set Before Creating:

   • Call /creationpartition immediately before creating entities
   • Ensures partition is always set, even after expiration
   • Adds overhead to every creation workflow

Setting Default Creation Partitions

Use the /creationpartition endpoint to set where new entities will be created.

Set single partition:

POST /creationpartition/201c7625-97b6-4ea6-a4d6-ff5cf279cdb4

Set multiple partitions:

POST /creationpartition/201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,a8a69df6-2ba5-4434-bf7f-4a4d911d56b2,fdc60e2e-5c02-41fc-9ea2-5aa57f30cfb1

Response:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Notes:

• You can set multiple default partitions
• Entities created after this call will be placed in these partitions
• This setting persists only for the duration of your session (5 minutes of inactivity ends the session; start a new session and set creation partitions again)
• If you do not set creation partitions, new entities follow the default partition assignment
• Applies only to entity types that support partitions; other entity types ignore this setting
• When you create a partition while this is set, that new partition is inserted into the partitions you specified
• If a listed partition is not accessible to the logged-on user, the call returns Rsp.Status = "Fail" with SdkErrorCode = "UnsufficientPrivilege" (HTTP 200). See the example below.

Failure response (partition not accessible):

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "SdkErrorCode": "UnsufficientPrivilege",
      "Message": "The current user doesn't have access to the specified partition: 201c7625-97b6-4ea6-a4d6-ff5cf279cdb4"
    }
  }
}

HTTP status is 200; rely on Rsp.Status and SdkErrorCode to detect the failure.

Querying Partitions

List All Partitions

GET /report/EntityConfiguration?q=EntityTypes@Partition,Page=1,PageSize=100

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      "00000000-0000-0000-0000-00000000000b",
      "201c7625-97b6-4ea6-a4d6-ff5cf279cdb4",
      "a8a69df6-2ba5-4434-bf7f-4a4d911d56b2"
    ]
  }
}

Notes:

• Returns partition GUIDs only
• Use pagination for large systems
• The GUID 00000000-0000-0000-0000-00000000000b is the default root partition

Get Partition Properties

GET /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,Name,Description,Members

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Name": "Building A",
      "Description": "All entities for Building A",
      "Members": [
        "12345678-1234-1234-1234-123456789abc",
        "87654321-4321-4321-4321-cba987654321"
      ]
    }
  }
}

Available fields:

• Name - Partition name
• Description - Partition description
• Members - Array of entity GUIDs that belong to this partition
• UserAccesses - Array of user/user group GUIDs that have access to this partition

Get Partition Members

GET /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,Members

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Members": [
        "12345678-1234-1234-1234-123456789abc",
        "87654321-4321-4321-4321-cba987654321",
        "abcdef12-3456-7890-abcd-ef1234567890"
      ]
    }
  }
}

Notes:

• Returns GUIDs of all entities in the partition
• Includes all entity types (doors, cameras, cardholders, etc.)
• Can return child partitions as well

Entity Partition Membership

Get Which Partitions an Entity Belongs To

POST /entity?q=entity=12345678-1234-1234-1234-123456789abc,GetPartitions()

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "GetPartitions": [
        "00000000-0000-0000-0000-00000000000b",
        "201c7625-97b6-4ea6-a4d6-ff5cf279cdb4"
      ]
    }
  }
}

Notes:

• An entity can belong to multiple partitions
• Returns array of partition GUIDs
• Entities always belong to at least one partition

Add Entity to Partition

POST /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,AddMember(12345678-1234-1234-1234-123456789abc)

Response:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Notes:

• First parameter is the partition GUID
• Second parameter is the entity GUID to add
• Both GUIDs and LogicalIDs are supported
• Requires write access to both the partition and the entity

Remove Entity from Partition

POST /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,RemoveMember(12345678-1234-1234-1234-123456789abc)

Response:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Notes:

• Entity will no longer be visible to users who only have access to this partition
• Entity must belong to at least one other partition, or the operation will fail
• Requires write access to the partition

Creating Partitions

Create a New Partition

POST /entity?q=entity=NewEntity(Partition),Name=Building B,Description=Entities for Building B,Guid

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Guid": "fdc60e2e-5c02-41fc-9ea2-5aa57f30cfb1"
    }
  }
}

Notes:

• Use NewEntity(Partition) to create a partition
• Set Name and optionally Description
• Include Guid in the projection to get the new partition's GUID
• Newly created partitions start with no members

User Access Control

Get Users with Access to Partition

GET /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,UserAccesses

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "UserAccesses": [
        "11111111-1111-1111-1111-111111111111",
        "22222222-2222-2222-2222-222222222222"
      ]
    }
  }
}

Notes:

• Returns GUIDs of users and user groups with access
• Includes access inherited from parent partitions in the hierarchy
• Users with partition access can see all entities in that partition

Add User Access to Partition

POST /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,AddUserAccess(11111111-1111-1111-1111-111111111111)

Response:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Notes:

• First parameter is partition GUID
• Second parameter is user or user group GUID
• Grants the user access to see all entities in the partition
• Requires write access to both partition and user

Remove User Access from Partition

POST /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,RemoveUserAccess(11111111-1111-1111-1111-111111111111)

Response:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Notes:

• User will no longer see entities in this partition
• Does not affect access inherited from parent partitions
• Requires write access to the partition

Complete Workflow Examples

Multi-Tenant Entity Creation

Scenario: Creating a cardholder in a specific tenant's partition

import requests

base_url = "https://server:4590/WebSdk"
headers = {"Authorization": "Basic ...", "Accept": "text/json"}

# Step 1: Set creation partition for Tenant A
requests.post(f"{base_url}/creationpartition/201c7625-97b6-4ea6-a4d6-ff5cf279cdb4", headers=headers)

# Step 2: Create cardholder (automatically goes into Tenant A partition)
response = requests.post(
    f"{base_url}/entity?q=entity=NewEntity(Cardholder),FirstName=John,LastName=Doe,Guid",
    headers=headers
)
cardholder_guid = response.json()["Rsp"]["Result"]["Guid"]

# Step 3: Verify partition membership
response = requests.post(
    f"{base_url}/entity?q=entity={cardholder_guid},GetPartitions()",
    headers=headers
)
print(f"Cardholder belongs to partitions: {response.json()['Rsp']['Result']['GetPartitions']}")

Moving Entity Between Partitions

Scenario: Transfer a camera from Building A to Building B partition

import requests

base_url = "https://server:4590/WebSdk"
headers = {"Authorization": "Basic ...", "Accept": "text/json"}

camera_guid = "12345678-1234-1234-1234-123456789abc"
partition_a = "201c7625-97b6-4ea6-a4d6-ff5cf279cdb4"  # Building A
partition_b = "a8a69df6-2ba5-4434-bf7f-4a4d911d56b2"  # Building B

# Step 1: Add camera to Building B partition
requests.post(f"{base_url}/entity?q=entity={partition_b},AddMember({camera_guid})", headers=headers)

# Step 2: Remove camera from Building A partition
requests.post(f"{base_url}/entity?q=entity={partition_a},RemoveMember({camera_guid})", headers=headers)

# Step 3: Verify new partition
response = requests.post(f"{base_url}/entity?q=entity={camera_guid},GetPartitions()", headers=headers)
print(f"Camera now in partitions: {response.json()['Rsp']['Result']['GetPartitions']}")

Granting User Access to Multiple Partitions

Scenario: Give a security manager access to all building partitions

import requests

base_url = "https://server:4590/WebSdk"
headers = {"Authorization": "Basic ...", "Accept": "text/json"}

user_guid = "11111111-1111-1111-1111-111111111111"
partitions = [
    "201c7625-97b6-4ea6-a4d6-ff5cf279cdb4",  # Building A
    "a8a69df6-2ba5-4434-bf7f-4a4d911d56b2",  # Building B
    "fdc60e2e-5c02-41fc-9ea2-5aa57f30cfb1"   # Building C
]

for partition_guid in partitions:
    response = requests.post(
        f"{base_url}/entity?q=entity={partition_guid},AddUserAccess({user_guid})",
        headers=headers
    )
    print(f"Added user to partition {partition_guid}: {response.json()['Rsp']['Status']}")

Common Patterns

Audit Partition Membership

List all entities in a partition with their types:

import requests

base_url = "https://server:4590/WebSdk"
headers = {"Authorization": "Basic ...", "Accept": "text/json"}

partition_guid = "201c7625-97b6-4ea6-a4d6-ff5cf279cdb4"

# Get all member GUIDs
response = requests.get(
    f"{base_url}/entity?q=entity={partition_guid},Members",
    headers=headers
)
members = response.json()["Rsp"]["Result"]["Members"]

# Get entity type for each member
for member_guid in members:
    response = requests.get(
        f"{base_url}/entity?q=entity={member_guid},Name,EntityType",
        headers=headers
    )
    result = response.json()["Rsp"]["Result"]
    print(f"{result['EntityType']}: {result['Name']} ({member_guid})")

Bulk Entity Assignment

Add multiple entities to a partition in a single request:

POST /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,AddMember(guid1),entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,AddMember(guid2),entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,AddMember(guid3)

System Partitions

Security Center automatically creates two special partitions (see Well-Known Entity GUIDs for complete list):

Root Partition

GUID: 00000000-0000-0000-0000-00000000000b

The root partition contains everything by default, and all users can see it unless you create additional partitions.

Characteristics:

• All entities belong to the root partition by default
• Cannot be deleted
• All users typically have access to the root partition
• Acts as the top-level partition in the hierarchy

System Partition

The system partition contains essential system entities and cannot be modified.

Characteristics:

• Contains core system entities required for Security Center operation
• Cannot be modified or deleted
• Managed automatically by the system

Error Handling

Common Errors

Entity not found:

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "SdkErrorCode": "UnableToRetrieveEntity",
      "Message": "Could not get the entity, does it exist? Guid: ..."
    }
  }
}

This response also occurs when the entity exists but the caller has no partition access to it.

Insufficient privileges:

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "SdkErrorCode": "UnsufficientPrivilege",
      "Message": "You only have read access on the user or user group specified..."
    }
  }
}

Cannot remove entity from last partition:

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "SdkErrorCode": "TransactionFailed",
      "Message": "Cannot remove entity from its last partition"
    }
  }
}

Limitations

• Partition settings are session-specific and reset on session expiration
• Entities must belong to at least one partition
• Partition hierarchy depth is not limited by the API but may have practical system limits
• User access changes may take a few seconds to propagate in large systems

See Also

• Getting Started - Session management and authentication
• Entity Operations - Creating and managing entities
• Referencing Entities - Entity discovery and querying
• Performance Guide - Session keep-alive and optimization