Tags

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

Property	Type	Description
`id`	`string`	Unique identifier
`scopeId`	`string`	Scope where this tag is defined
`tagGroupId`	`string`	The tag group this tag belongs to
`identifier`	`string`	Machine-readable key
`label`	`string`	Human-readable display name
`createdBy`	`string`	Subject who created it
`createdAt`	`Date`	Creation timestamp

Creating Tags

Tags must belong to a tag group. You can create them in two ways:

Option 1: Inline Tags (Recommended)

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 Type	Description
`scope`	Scopes
`resource`	Resource instances
`subject`	Users, agents, services
`role`	Roles
`membership`	Memberships

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.

The example below shows subject-tag matching, which is not enforced yet—the engine doesn’t load subject tags (see the roadmap and Tag-Based Access). Resource-side tag conditions do work today. Conditions also attach to the role-permission edge (condition), not a permission logic field.

# (Intended model) 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

Getting Started

Core Concepts

Resources

Delegation

Use Cases

Modeling Guides

Tags

What are Tags?

Tag Groups

Tag Bindings

Tag-Based Access

Tag Properties

Creating Tags

Option 1: Inline Tags (Recommended)

Option 2: Separate Requests

Assigning Tags

Tag a Resource

Tag a Subject

Taggable Models

Departments (Multi-Select)

Sensitivity Levels (Single-Select)

Project Categories

Labor Classes (Construction)

Using Tags in Permissions

Tag-Based Access

API Reference

Create Tag Group

Create Tag

Get Tags

Get Tag Groups

Next Steps

Tag Groups

​What are Tags?

Tag Groups

Tag Bindings

Tag-Based Access

​Tag Properties

​Creating Tags

​Option 1: Inline Tags (Recommended)

​Option 2: Separate Requests

​Assigning Tags

​Tag a Resource

​Tag a Subject

​Taggable Models

​Common Tag Group Patterns

​Departments (Multi-Select)

​Sensitivity Levels (Single-Select)

​Project Categories

​Labor Classes (Construction)

​Using Tags in Permissions

Tag-Based Access

​API Reference

Create Tag Group

Create Tag

Get Tags

Get Tag Groups

​Next Steps

Tag Groups

What are Tags?

Tag Properties

Creating Tags

Option 1: Inline Tags (Recommended)

Option 2: Separate Requests

Assigning Tags

Tag a Resource

Tag a Subject

Taggable Models

Common Tag Group Patterns

Departments (Multi-Select)

Sensitivity Levels (Single-Select)

Project Categories

Labor Classes (Construction)

Using Tags in Permissions

API Reference

Next Steps