Acquire Working Instance

Before you can create or modify data in acre Access Control, you need to establish which instance you’re working with. This guide shows you how to get your current instance and navigate the instance hierarchy.

Overview

What is an Instance?

An instance is a logical container that holds all your access control data—people, cards, readers, controllers, and configurations. Think of it as your isolated workspace within the acre Access Control cloud.

Concept Description
Current Instance The instance your user account is authenticated to
Child Instances Sub-instances that inherit from a parent (multi-tenant scenarios)
Instance Key Unique identifier used in all API calls

When You Need an Instance

Operation Instance Required
Create people, cards, or access levels ✅ Yes
Add hardware (controllers, readers) ✅ Yes
Query event history ✅ Yes
Get server information ❌ No (pre-authentication)

Get Current Instance

The most common operation is retrieving your current (authenticated) instance.

C# Example

// Get the instance associated with your authentication
var currentInstance = await client.GetCurrentInstanceAsync();

// The instance contains useful information
Console.WriteLine($"Instance Name: {currentInstance.CommonName}");
Console.WriteLine($"Instance Key: {currentInstance.Key}");
Console.WriteLine($"Domain: {currentInstance.FullyQualifiedDomainName}");
Console.WriteLine($"Self Link: {currentInstance.Href}");

cURL Example

# Get current instance information
curl -X GET \
  https://api.us.acresecurity.cloud/api/ \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response Structure

{
  "$type": "Feenics.Keep.WebApi.Model.InstanceInfo, Feenics.Keep.WebApi.Model",
  "Key": "5b61d62492dacd062c424424",
  "CommonName": "YourCompany.Production",
  "FullyQualifiedDomainName": "yourcompany.production.acresecurity.cloud",
  "Href": "/api/f/5b61d62492dacd062c424424",
  "TimeZone": "America/New_York",
  "IsDisabled": false,
  "Links": [],
  "ObjectLinks": [],
  "Metadata": [],
  "Notes": [],
  "Tags": [],
  "Monikers": []
}

Working with the Instance

Once you have the instance, you can use it for all data operations.

Creating Objects in an Instance

// Use the instance to create objects
var person = await client.AddPersonAsync(currentInstance, new PersonInfo
{
    CommonName = "John Doe",
    GivenName = "John",
    Surname = "Doe"
});

var accessLevel = await client.AddAccessLevelAsync(currentInstance, new AccessLevelInfo
{
    CommonName = "General Access"
});

Searching Within an Instance

// Search for people in the current instance
var people = await client.SearchAsync(currentInstance, "{\"_t\":\"Person\",\"GivenName\":\"John\"}");

foreach (var person in people.OfType<PersonInfo>())
{
    Console.WriteLine($"Found: {person.CommonName}");
}

For multi-tenant or enterprise deployments, you may need to work with child instances.

Get Child Instances

// Get all child instances under the current instance
// Use includeChildFolders=true to search in child folders
var children = await client.SearchAsync(currentInstance, "{\"_t\":\"Instance\"}", 
    includeChildFolders: true);

foreach (var child in children.OfType<InstanceInfo>())
{
    Console.WriteLine($"Child Instance: {child.CommonName}");
}

Switch to a Different Instance

// Switch to a specific child instance
var targetInstance = children.FirstOrDefault(i => i.CommonName == "Building-A");

if (targetInstance != null)
{
    // Now use targetInstance for operations in that scope
    var buildingAPeople = await client.SearchAsync(targetInstance, "{\"_t\":\"Person\"}");
}

cURL: List Child Instances

# Get child instances using search with includeChildFolders parameter
curl -X POST \
  'https://api.us.acresecurity.cloud/api/f/INSTANCE_KEY/search?includeChildFolders=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"_t":"Instance"}'

Common Patterns

Store Instance Reference

public class AccessControlService
{
    private readonly Client _client;
    private InstanceInfo _currentInstance;
    
    public async Task InitializeAsync()
    {
        // Cache the instance reference for reuse
        _currentInstance = await _client.GetCurrentInstanceAsync();
    }
    
    public async Task<PersonInfo> AddPersonAsync(string firstName, string lastName)
    {
        return await _client.AddPersonAsync(_currentInstance, new PersonInfo
        {
            CommonName = $"{lastName}, {firstName} ",
            GivenName = firstName,
            Surname = lastName
        });
    }
}

Validate Instance Before Operations

var instance = await client.GetCurrentInstanceAsync();

if (instance == null)
{
    throw new InvalidOperationException("Failed to retrieve current instance. Check authentication.");
}

if (instance.IsDisabled)
{
    throw new InvalidOperationException($"Instance '{instance.CommonName}' is disabled.");
}

// Safe to proceed
var person = await client.AddPersonAsync(instance, newPerson);

Best Practices

Practice Recommendation
Cache Instance Get the instance once and reuse it for multiple operations
Check for Null Always verify the instance was retrieved successfully
Use Correct Scope Ensure you’re working in the right instance for multi-tenant setups
Handle Disabled Instances Check IsDisabled before attempting operations

Troubleshooting

Issue Cause Solution
null instance returned Authentication failed Verify credentials and token
Wrong data scope Working in wrong instance Check CommonName matches expected
InstanceDoesNotExist error Invalid instance key Use key from GetCurrentInstanceAsync
InstanceIsDisabled error Instance has been disabled Contact administrator

See Also