Skip to main content

​
What are Tags?

Tags provide flexible, attribute-based classification for resources and subjects. Unlike hierarchical structures, tags allow many-to-many relationships—a document can be tagged as both “confidential” and “finance” and “q4-2024”. Tags enable:
  • Attribute-based access control (ABAC)
  • Dynamic filtering and queries
  • Conditional permissions based on tag matching

Tag Groups

Organize related tags together

Tag Bindings

Control which models can use which tag groups

Tag-Based Access

Use tags in permission conditions

​
Tag Properties

PropertyTypeDescription
idstringUnique identifier
scopeIdstringScope where this tag is defined
tagGroupIdstringThe tag group this tag belongs to
identifierstringMachine-readable key
labelstringHuman-readable display name
createdBystringSubject who created it
createdAtDateCreation timestamp

​
Creating Tags

Tags must belong to a tag group. You can create them in two ways: Create a tag group with its tags in a single request: 
curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Departments",
    "key": "departments",
    "description": "Company departments",
    "tags": [
      {"identifier": "engineering", "label": "Engineering"},
      {"identifier": "sales", "label": "Sales"},
      {"identifier": "finance", "label": "Finance"},
      {"identifier": "hr", "label": "Human Resources"}
    ]
  }'
Inline tags automatically inherit scopeId and tagGroupId from the parent group.

​
Option 2: Separate Requests

Create the tag group first, then add tags: 
# First, create a tag group
curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Departments",
    "key": "departments",
    "description": "Company departments"
  }'

# Then create tags in that group
curl -X POST 'https://api.example.com/tags/batch' \
  -d '[
    {"scopeId": "scope_project", "tagGroupId": "tg_departments", "identifier": "engineering", "label": "Engineering"},
    {"scopeId": "scope_project", "tagGroupId": "tg_departments", "identifier": "sales", "label": "Sales"},
    {"scopeId": "scope_project", "tagGroupId": "tg_departments", "identifier": "finance", "label": "Finance"},
    {"scopeId": "scope_project", "tagGroupId": "tg_departments", "identifier": "hr", "label": "Human Resources"}
  ]'

​
Assigning Tags

Tags can be assigned to resources and subjects:

​
Tag a Resource

curl -X POST 'https://api.example.com/tag-assignments' \
  -d '{
    "tagId": "tag_finance",
    "targetType": "resource",
    "targetId": "resource_doc_123",
    "scopeId": "scope_org"
  }'

​
Tag a Subject

curl -X POST 'https://api.example.com/tag-assignments' \
  -d '{
    "tagId": "tag_engineering",
    "targetType": "subject",
    "targetId": "subject_jane",
    "scopeId": "scope_org"
  }'

​
Taggable Models

The TaggableModelTypeEnum defines what can be tagged:
Model TypeDescription
resourceResource instances
subjectUsers, agents, services
roleRoles
permissionPermissions

​
Common Tag Group Patterns

​
Departments (Multi-Select)

curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Departments",
    "key": "departments",
    "description": "Organization departments",
    "tags": [
      {"identifier": "engineering", "label": "Engineering"},
      {"identifier": "sales", "label": "Sales"},
      {"identifier": "finance", "label": "Finance"},
      {"identifier": "hr", "label": "Human Resources"}
    ]
  }'

​
Sensitivity Levels (Single-Select)

curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Sensitivity",
    "key": "sensitivity",
    "description": "Data sensitivity classification",
    "maxAppliedPerTarget": 1,
    "tags": [
      {"identifier": "public", "label": "Public"},
      {"identifier": "internal", "label": "Internal"},
      {"identifier": "confidential", "label": "Confidential"},
      {"identifier": "restricted", "label": "Restricted"}
    ]
  }'

​
Project Categories

curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Project Type",
    "key": "project_type",
    "description": "Type of project",
    "tags": [
      {"identifier": "client-work", "label": "Client Work"},
      {"identifier": "internal", "label": "Internal"},
      {"identifier": "research", "label": "Research"}
    ]
  }'

​
Labor Classes (Construction)

curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Labor Classes",
    "key": "labor_classes",
    "description": "Worker classifications",
    "tags": [
      {"identifier": "electrician", "label": "Electrician"},
      {"identifier": "plumber", "label": "Plumber"},
      {"identifier": "carpenter", "label": "Carpenter"},
      {"identifier": "foreman", "label": "Foreman"}
    ]
  }'

​
Using Tags in Permissions

Tags enable attribute-based access control: 
# Permission: Users can only read documents tagged with their department
curl -X POST 'https://api.example.com/permissions' \
  -d '{
    "scopeId": "scope_project",
    "action": "read",
    "resourceType": "document",
    "resourcePattern": "*",
    "key": "document:read:dept-match",
    "label": "Read Department Documents",
    "logic": {
      "some": [
        {"var": "resource.tags.departments"},
        {"in": [{"var": ""}, {"var": "subject.tags.departments"}]}
      ]
    }
  }'

Tag-Based Access

Learn more about using tags in permission conditions

​
API Reference

Create Tag Group

Create a new tag group

Create Tag

Create a tag in a group

Get Tags

List tags

Get Tag Groups

List tag groups

​
Next Steps

Tag Groups

Learn how to organize tags with groups and constraints