Skip to main content

Using Control Tags for Additional Access Controls

Control tags provide an additional layer of access control beyond standard sharing permissions. They are used to:

  • Restrict visibility of sensitive resources
  • Enforce compliance or regulatory boundaries
  • Segment access within and across tenants
  • Prevent accidental oversharing of confidential data

⚠️ Control tags do not grant access. They restrict access.

Access Rules​

General Rules​

To access a model or artifact with control tags:

  • The user must already be a Viewer or Editor of the resource.
  • The user must also have every control tag assigned to the resource assigned to their user account.
  • Model and Artifact Owners/Administrators can always access the resources they manage, regardless of control tags.

Who Manages Control Tags​

  • User control tag assignments: Tenant administrators
  • Model control tags: Model Owners and Administrators
  • Artifact control tags: Artifact Owners and the Owners or Administrators of the parent model

Tag Inheritance and Assignment​

Model-Level Tags​

  • Tags assigned to a model are automatically inherited by all its artifacts.
  • Removing a tag from a model also removes it from any artifacts that inherited it.

Artifact-Level Tags​

  • Tags can also be assigned directly to individual artifacts.
  • If the same tag is later added or removed at the model level, that model-level change overrides the artifact-level assignment for that tag.
  • Artifacts may have more restrictive or less restrictive access than their model depending on tag overrides.

Note: Inheritance flows from model → artifact only.

Example Scenario​

  1. Alice has the SENSITIVE tag assigned to her user account.
  2. Bob creates a model and shares it with Alice and George.
  3. Bob adds the SENSITIVE tag to the model.
    • Alice keeps access (she has the tag).
    • George loses access (he lacks the tag).
  4. An admin removes the tag from Alice's account.
    • Alice loses access.
  5. Bob removes the tag from the model.
    • George and Alice regain access.
  6. Bob assigns the SENSITIVE tag directly to an artifact.
    • George cannot access the artifact.
    • Alice regains access after the tag is reassigned to her.

Creating Control Tags​

Who Can Create​

Only Tenant Administrators.

How to Create​

In the Web App:

  1. Open the Admin Panel from the left sidebar.
  2. Select Control Tags.
  3. Click + New Control Tag.
  4. Provide a name, optional description, and optional display color.
  5. Click Create.

Tag names are automatically converted to ALL CAPS.

Using the Python SDK:

from istari_digital_client import Client, Configuration, NewControlTag

client = Client(Configuration(
    registry_url='[REGISTRY_URL]',
    registry_auth_token='[ACCESS_TOKEN]'
))

tag = client.create_control_tag(
    NewControlTag(
        name="SENSITIVE",
        description="Restricted access tag",
        display_color="magenta"
    )
)

Archiving and Restoring Control Tags​

Archiving​

Who: Tenant Administrators
Effect: Removes tag and all assignments from users, models, and artifacts. These resources behave as if the tag was never applied.

SDK Example:

archived_tag = client.update_control_tag(
    UpdateControl_tag(id=tag.id, status=ControlTagStatus.ARCHIVED)
)

Restoring​

Effect: Restores model/artifact tag assignments; user tag assignments must be re-added manually.

SDK Example:

restored_tag = client.update_control_tag(
    UpdateControlTag(id=archived_tag.id, status=ControlTagStatus.ACTIVE)
)

Editing Control Tags​

Editable Fields:

  • Name (must be unique)
  • Description (optional)
  • Display color (optional)

SDK Example:

updated_tag = client.update_control_tag(
    UpdateControlTag(id=tag.id,
                     name="CONFIDENTIAL",
                     description="Internal use only",
                     display_color="#ff0000")
)

Control Tag Revision History​

Every change to a control tag creates a new revision. Revisions are fully auditable and include user and timestamp metadata.

SDK Example:

revisions = client.get_control_tag_revision_history(control_tag_id=tag.id)

Tag Assignment History​

The Istari platform preserves the history of all control tag assignments and removals.

SDK Examples:

# For a model
taggings = client.get_model_control_tagging_history("[MODEL_ID]")

# For an artifact
taggings = client.get_artifact_control_tagging_history("[ARTIFACT_ID]")

# For a user
taggings = client.get_user_control_tagging_history("[USER_ID]")

Assigning Control Tags to Models and Artifacts​

Who Can Assign​

  • Model Owners and Administrators (for models)
  • Artifact Owners, and Owners/Administrators of the parent model (for artifacts)

How to Assign (Web App)​

  1. Navigate to a model or artifact detail page.
  2. Click + Add Control Tags if none are assigned, or click the edit icon beside existing tags.
  3. Select or deselect available tags.
  4. (Optional) Add a reason for the change.
  5. Click Save.

SDK Example​

# Add tags
client.add_model_control_taggings(
    model_id=model.id,
    control_tag_ids=[tag1.id, tag2.id],
    reason="initial tagging"
)

# Remove tags
client.remove_model_control_taggings(
    model_id=model.id,
    control_tag_ids=[tag2.id],
    reason="removing one tag"
)

Assigning Control Tags to Users​

Who Can Assign​

Tenant Administrators (must have customer_admin label in Zitadel)

How to Assign (Web App)​

  1. Open the Admin Panel and navigate to Control Tags.
  2. Click the Control Tag Permissions tab.
  3. Click Add Control Tags or Edit Control Tags next to a user.
  4. Select tags to assign or remove, then click Save.

SDK Example​

# Add tags
client.add_user_control_taggings(
    user_id=user.id,
    control_tag_ids=[tag1.id, tag2.id],
    reason="initial access assignment"
)

# Remove tags
client.remove_user_control_taggings(
    user_id=user.id,
    control_tag_ids=[tag1.id],
    reason="access removed"
)

Summary​

  • Control tags are restrictive, not permissive—they add constraints to existing share-based access.
  • Both sharing and tag access are required to view tagged resources.
  • Model and artifact owners/administrators always retain access regardless of tags.
  • Tag inheritance flows from model → artifact.
  • Archived tags remove all assignments but can be restored later.
  • Revision and assignment history is retained for audit and compliance.