Create a Badge Type

Overview

Badge types define categories of credentials in the access control system. They control visual appearance for printed badges, default expiration settings, and can be linked to access levels for automatic permission assignment. When a person is assigned a badge type, they automatically inherit the access levels linked to that badge type.

Badge Type Properties

Property Type Description
CommonName string Unique identifier/display name for the badge type
AbsoluteExpiryDate DateTime? Fixed date when all badges of this type expire
SlidingExpirySpan TimeSpan? Duration from activation until expiration
Width double Badge width in pixels for printing
Height double Badge height in pixels for printing
BackgroundColor string Front side background color
BackBackgroundColor string Back side background color
FrontOrientation int Front side print orientation (0=Landscape, 1=Portrait)
BackOrientation int Back side print orientation (0=Landscape, 1=Portrait)
FrontBorderThickness double Front side border width
BackBorderThickness double Back side border width

Expiration Strategies

Strategy Property Use Case
Absolute Expiry AbsoluteExpiryDate All badges expire on a fixed date (e.g., end of fiscal year)
Sliding Expiry SlidingExpirySpan Badges expire after a duration from activation (e.g., 1 year from issue)

Note: If both properties are set, AbsoluteExpiryDate takes precedence.

Creating a Badge Type

Basic Badge Type with Absolute Expiration

var badgeType = await client.AddBadgeTypeAsync(currentInstance, new BadgeTypeInfo
{
    CommonName = "Employee Badge",
    AbsoluteExpiryDate = new DateTime(2025, 12, 31)  // All badges expire on Dec 31, 2025
});

Console.WriteLine($"Created badge type: {badgeType.CommonName} (Key: {badgeType.Key})");

Badge Type with Sliding Expiration

// Badges expire 1 year after activation
var contractorBadge = await client.AddBadgeTypeAsync(currentInstance, new BadgeTypeInfo
{
    CommonName = "Contractor Badge",
    SlidingExpirySpan = TimeSpan.FromDays(365)  // 1 year from card activation
});

Badge Type with Visual Properties

var executiveBadge = await client.AddBadgeTypeAsync(currentInstance, new BadgeTypeInfo
{
    CommonName = "Executive Badge",
    SlidingExpirySpan = TimeSpan.FromDays(730),  // 2 years
    
    // Physical dimensions (in pixels)
    Width = 1012,   // pixels (standard CR80 card width at 300 DPI)
    Height = 638,   // pixels (standard CR80 card height at 300 DPI)
    
    // Visual styling
    BackgroundColor = "#1E3A8A",       // Navy blue front
    BackBackgroundColor = "#FFFFFF",   // White back
    FrontOrientation = 0,              // Landscape (0=Landscape, 1=Portrait)
    BackOrientation = 0,               // Landscape
    
    // Border settings
    FrontBorderThickness = 2.0,
    FrontBorderBrush = "#D4AF37",      // Gold border
    BackBorderThickness = 1.0,
    BackBorderBrush = "#333333"        // Dark gray border
});

Linking Access Levels to Badge Types

When a person is assigned a badge type, they automatically receive its linked access levels:

// Create badge type
var badgeType = await client.AddBadgeTypeAsync(currentInstance, new BadgeTypeInfo
{
    CommonName = "Security Staff Badge",
    SlidingExpirySpan = TimeSpan.FromDays(365)
});

// Get access levels to link
var allDoorsAccess = (await client.SearchAsync(currentInstance, "{\"_t\": \"AccessLevel\", \"CommonName\":\"All Doors Access\"}"))
    .OfType<AccessLevelInfo>().FirstOrDefault();
var securityOffice = (await client.SearchAsync(currentInstance, "{\"_t\": \"AccessLevel\", \"CommonName\":\"Security Office\"}"))
    .OfType<AccessLevelInfo>().FirstOrDefault();

// Link access levels to badge type
// isOneToOne = false because an access level can be on many badge types
await client.AssignConnectedObjectAsync(badgeType, allDoorsAccess, "AccessLevel", false);
await client.AssignConnectedObjectAsync(badgeType, securityOffice, "AccessLevel", false);

Console.WriteLine("Linked access levels to badge type");

Common Badge Type Categories

Category Expiration Typical Access
Full-Time Employee 1-2 years sliding All standard doors
Contractor 90-365 days sliding Limited areas
Visitor 1 day sliding Lobby only
Temporary 30 days sliding Specific project areas
Executive 2 years sliding All doors + executive areas
Security 1 year sliding All doors + security office

Create Common Badge Types

// Full-time employee badge
var employeeBadge = await client.AddBadgeTypeAsync(currentInstance, new BadgeTypeInfo
{
    CommonName = "Full-Time Employee",
    SlidingExpirySpan = TimeSpan.FromDays(365)
});

// Contractor badge (shorter duration)
var contractorBadge = await client.AddBadgeTypeAsync(currentInstance, new BadgeTypeInfo
{
    CommonName = "Contractor",
    SlidingExpirySpan = TimeSpan.FromDays(90)
});

// Visitor badge (single day)
var visitorBadge = await client.AddBadgeTypeAsync(currentInstance, new BadgeTypeInfo
{
    CommonName = "Visitor",
    SlidingExpirySpan = TimeSpan.FromDays(1)
});

Assigning Badge Types to People

// Get the badge type
var badgeType = (await client.SearchAsync(currentInstance, "{\"_t\": \"BadgeType\", \"CommonName\":\"Full-Time Employee\"}"))
    .OfType<BadgeTypeInfo>().FirstOrDefault();

// Create person first
var person = await client.AddPersonAsync(currentInstance, new PersonInfo
{
    CommonName = "JohnDoe",
    GivenName = "John",
    Surname = "Doe"
});

// Assign badge type after creation using AssignConnectedObjectAsync
await client.AssignConnectedObjectAsync(person, badgeType, "BadgeType", false);

Console.WriteLine($"Assigned badge type '{badgeType.CommonName}' to {person.CommonName}");

Retrieving Badge Types

// Get all badge types in the instance
var allBadgeTypes = await client.GetBadgeTypesAsync(currentInstance);

foreach (var badge in allBadgeTypes)
{
    Console.WriteLine($"Badge: {badge.CommonName}");
    if (badge.AbsoluteExpiryDate.HasValue)
        Console.WriteLine($"  Expires: {badge.AbsoluteExpiryDate.Value:yyyy-MM-dd}");
    if (badge.SlidingExpirySpan.HasValue)
        Console.WriteLine($"  Valid for: {badge.SlidingExpirySpan.Value.TotalDays} days");
}

// Get specific badge type
var specific = (await client.SearchAsync(currentInstance, "{\"_t\": \"BadgeType\", \"CommonName\":\"Executive Badge\"}"))
    .OfType<BadgeTypeInfo>().FirstOrDefault();

cURL Examples

Create Badge Type

curl -X POST \
  "https://api.us.acresecurity.cloud/api/f/INSTANCE_KEY/badgetypes" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "$type": "Feenics.Keep.WebApi.Model.BadgeTypeInfo, Feenics.Keep.WebApi.Model",
    "CommonName": "Employee Badge",
    "SlidingExpirySpan": "365.00:00:00"
  }'

Create Badge Type with Absolute Expiration

curl -X POST \
  "https://api.us.acresecurity.cloud/api/f/INSTANCE_KEY/badgetypes" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "$type": "Feenics.Keep.WebApi.Model.BadgeTypeInfo, Feenics.Keep.WebApi.Model",
    "CommonName": "Fiscal Year Badge",
    "AbsoluteExpiryDate": "2025-12-31T23:59:59Z"
  }'

curl -X PUT \
  "https://api.us.acresecurity.cloud/api/f/INSTANCE_KEY/badgetypes/BADGE_TYPE_KEY/connections/AccessLevel?isOneToOne=false&relatedKey=ACCESS_LEVEL_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get All Badge Types

curl -X GET \
  "https://api.us.acresecurity.cloud/api/f/INSTANCE_KEY/badgetypes" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Best Practices

Practice Recommendation
Naming Use descriptive names (Employee, Contractor, Visitor, Temporary)
Expiration Always set expiration - avoid perpetual badges
Sliding vs Absolute Use sliding for new systems, absolute for annual renewal cycles
Access Levels Link default access levels to badge types for automation
Categories Create distinct badge types for different user categories
Visual Identity Use colors/styling to visually distinguish badge categories