arrow-left

All pages
gitbookPowered by GitBook
1 of 3

Loading...

Loading...

Loading...

Promoted Tags

Operations for adding, removing, and listing tags for entity enrichment.

circle-check

Tag promotion for Access Reviews is currently available in Early Access. Please contact our support team to enable this capability.

Use these APIs to define the tags Veza should treat as customer-defined properties. Access Reviews that involve these entity types will include columns showing the tag name and value.

For example, in AWS, you may automatically tag identities with a 3rd-party security tool, or use tags to label S3 buckets containing sensitive data. When a tag is promoted, Veza Access Reviews will treat the tag as a built-in entity attribute, and show this information for reviewers in an optional column.

hashtag
Promote tag

Add a promotion rule by specifying its type and key, and the entity types it applies to:

  • include_entity_types: if true, promote tags for the listed type(s).

  • exclude_entity_type: if true, promotes tags for all entities except the listed type(s).

You can promote tags for any integration that supports them, such as Snowflake or Google Cloud. Use for integrations that do not support vendor-native tags or when built-in tagging is unavailable. Example tag types:

  • AWSTag

  • CookieTag (Veza Tag)

  • GoogleCloudLabel

Entity types for tag promotion should be concrete types. You can confirm the format by viewing details for any graph node, and checking the Type attribute, for example:

  • OAA.PagerDuty.User

  • ActiveDirectoryUser

  • OAA.custom_idp.IDPUser

hashtag
Demote tag

Remove a promotion rule for the specified tag key and type. Demotions apply on the next data source parse.

hashtag
List tag promotions

Get all promotion rules for all entity types.

Tags

Create, apply, and remove Veza tags

Tagging is a product capability allowing organizations to add additional metadata to the entities (such as users, roles, tables, or any other resource/identity) discovered by Veza.

curl 'https://{{VezaUrl}}/api/v1/graph/nodes/veza_tags' \
  --data-raw '{
      "node_id":"arn:aws:s3:::aws-cloudtrail-logs-527398259632-c98becd0",
      "tags":[
          {"key":"custom_tag","value":"one"}
        ]
    }'

You can filter search results for entities with a given tag, create access workflows based on tags, or use them to add context and notes that other users can view and search by.

To apply a tag, you will need the ID of the node to modify. Calling get query nodes will return IDs as part of the search result. You can also retrieve this value by clicking Show Details for the entity in Access Graph, or checking the ID column from Identity Data Entities or the Query Builder.

hashtag
Quick Start

Generate a bearer token from .

For the examples below, BASEURL should be the address of your Veza instance, such as https://<org>.vezacloud.com.

Use Get Query Spec Nodes to find Snowflake tables reachable by federated Okta users belonging to the Finance department:

The response will include the table id:

Apply a tag by specifying a key and optional value:

Remove a tag by providing the entity id and the tag key to delete:

Create, Add, Remove Tag

Create, apply, and remove Veza tags

New in 2025.11.24: Bulk tagging operations are now available as part of the private/ API set.

Use these APIs to create, add, and remove Veza tags. These endpoints support bulk onboarding of external tags into Veza Access Graph, environment migrations, and maintaining at scale.

hashtag
Methods

export BASEURL=https://<org>.vezacloud.com} \
export TOKEN=Sk9lcmEta2w2c2padklkaDhOcDVhTWdVU3FlTlpVajg=
Administration > API Keys
curl $BASEURL/api/v1/assessments/query_spec:nodes \
  -H 'authorization: Bearer '$TOKEN \
  --data-raw '{
  "query_type": "SOURCE_TO_DESTINATION",
  "include_nodes": true,
  "source_node_types": {
    "nodes": [
      {
        "node_type": "SnowflakeTable"
      }
    ]
  },
  "destination_node_types": {
    "nodes": [
      {
        "node_type": "OktaUser",
        "condition_expression": {
          "specs": [
            {
              "fn": "CONTAINS",
              "property": "department",
              "value": "Finance"
            }
          ]
        }
      }
    ]
  }
}'
{
  "values": [
    {
      "id": "dn44266.us-east-2.aws.snowflakecomputing.com/database/LOCATION/schema/COUNTRIES/table/USA",
      "type": "SnowflakeTable",
      "properties": {
        "created_at": "2021-05-14T21:18:55Z",
        "name": "USA"
      },
      "destination_node_count": 1,
      "permissions": []
    }
  ],
  "next_page_token": "MzA=",
  "has_more": false
  }
curl $BASEURL/api/v1/graph/nodes/veza_tags \
  -H 'authorization: Bearer '$TOKEN \
  --data-raw '{
  "node_id": "dn44266.us-east-2.aws.snowflakecomputing.com/database/LOCATION/schema/COUNTRIES/table/USA",
  "tags": [
    {
      "key": "department",
      "value": "finance"
    }
  ]
  }'
  curl $BASEURL/api/v1/graph/veza_tags:remove \
  -H 'authorization: Bearer '$TOKEN \
  --data-raw '{
  "node_id": "dn44266.us-east-2.aws.snowflakecomputing.com/database/LOCATION/schema/COUNTRIES/table/USA",
  "tag_key": "department"
  }'
hashtag
Create Veza Tag

Post {VezaURL}/api/v1/graph/tags

Define a new tag that can be applied to any discovered entity, as a key:value pair. The tag value is optional.

Parameter
In
Description

tag

body

Contains a single key:value pair

key

body

Max length 255 characters (alphanumeric and _)

A successful response will be empty ({}).

hashtag
Add Veza Tag

Post {VezaURL}/api/v1/graph/nodes/tags

Apply one or more tags to an entity by providing an entity ID. A new Tag will be created if one doesn't already exist.

Parameter
In
Description

node_id

body

Veza entity ID

tags

body

Array of tags to add

To retrieve an entity ID, you can use the Query Builder API, or browse the Identity Data Entities catalog.

hashtag
Remove Veza Tag

Post {VezaURL}/api/v1/graph/nodes/tags:remove

Remove one or more tags from an entity.

Parameter
In
Description

node_id

body

ID of the entity to modify

tag_keys

body

Array of tag keys to remove (1-100 tags)

Remove single tag (legacy format):

Remove multiple tags (recommended):

A successful response will be empty ({}).

hashtag
Bulk Tag Operations

Post {VezaURL}/graph/private/tags:bulk

Add or remove tags from multiple entities in a single atomic operation. All operations execute within a single transaction; if any operation encounters a retryable error, the entire transaction rolls back.

Parameter
In
Description

add

body

Array of add tag requests

remove

body

Array of remove tag requests

circle-info

Operation Limit: Maximum of 10,000 total tag operations per request (combined count of all tags added or removed across all nodes).

Validation rules:

  • Each add request: supports 1-100 tags per node

  • Each remove request: supports 1-100 tag keys per node

  • Total operations (all tags in all add/remove requests): Maximum 10,000

  • Tag keys: 1-255 characters (alphanumeric and _)

  • Tag values: Maximum 4,096 characters

Add tags to multiple nodes:

Remove tags from multiple nodes:

Combined add and remove operations:

A successful response will be empty ({}).

Veza Tags
Promote tag
Demote tag
List tag promotions
Veza tags
{
    "tag": {
        "key": "note",
        "value": "tags_can_be_used_as_searchable_properties,_or_add_extended_notes"
    }
}
{
    "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
    "tags": [
        {
            "key": "PII",
            "value": "GRPC"
        },
        {
            "key": "environment",
            "value": "production"
        }
    ]
}
{
 "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
 "tag_key": "environment"
}
{
 "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
 "tag_keys": ["environment", "department", "owner"]
}
{
 "add": [
  {
   "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
   "tags": [
    {
     "key": "environment",
     "value": "production"
    },
    {
     "key": "department",
     "value": "engineering"
    }
   ]
  },
  {
   "node_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
   "tags": [
    {
     "key": "environment",
     "value": "production"
    }
   ]
  }
 ]
}
{
 "remove": [
  {
   "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
   "tag_keys": ["temporary", "archived"]
  },
  {
   "node_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
   "tag_keys": ["temporary"]
  }
 ]
}
{
 "add": [
  {
   "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
   "tags": [
    {
     "key": "status",
     "value": "active"
    }
   ]
  }
 ],
 "remove": [
  {
   "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
   "tag_keys": ["temporary"]
  },
  {
   "node_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
   "tag_keys": ["archived", "deprecated"]
  }
 ]
}

value

body

Max length 4096 characters.

tag_key

body

Deprecated: Single tag key to remove

hashtag
Promote Tag

post

Adds a promoted tag. If a promoted tag with the same tag_key and tag_type already

exists, a unique constraint error will be returned without modifying the existing

promoted tag.

Authorizations
AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Body
tag_keystringOptional

tag_key and tag_type specify the tag to be promoted

tag_typeinteger · enumOptional
include_entity_typesstring[]Optional

Only one or the other makes sense to be set. include_entity_types indicates promote only for the listed type exclude_entity_type indicates promote for any type except for the listed types The types should be concrete types, and OAA types should be supplied with their native types name, ie "OAA.ApplicationName.Type".

exclude_entity_typesstring[]Optional
post
/api/preview/graph/tag_promotions

hashtag
Demote Tag

post

Demotes a promoted tag

Authorizations
AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Body
tag_keystringOptional
tag_typeinteger · enumOptional
Responses
chevron-right
200

OK

application/json
objectOptional
chevron-right
default

Default error response

application/json

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

codeinteger · int32Optional

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

messagestringOptional

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

@typestringOptional

The type of the serialized message.

Other propertiesanyOptional
post
/api/preview/graph/tag_promotions:demote

hashtag
List Tag Promotions

get

List promoted tags

Authorizations
AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Responses
chevron-right
200

OK

application/json
tag_keystringOptional
tag_typeinteger · enumOptional
include_entity_typesstring[]Optional

Only one or the other is accepted, if both are supplied the request is considered invalid. If "include_entity_types" is empty, all types will be included except any that are in "exclude_entity_types".

exclude_entity_typesstring[]Optional
chevron-right
default

Default error response

application/json

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

codeinteger · int32Optional

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

messagestringOptional

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

@typestringOptional

The type of the serialized message.

Other propertiesanyOptional
get
/api/preview/graph/tag_promotions
Responses
chevron-right
200

OK

application/json
objectOptional
chevron-right
default

Default error response

application/json

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

codeinteger · int32Optional

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

messagestringOptional

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

@typestringOptional

The type of the serialized message.

Other propertiesanyOptional
POST /api/preview/graph/tag_promotions HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "tag_key": "text",
  "tag_type": 1,
  "include_entity_types": [
    "text"
  ],
  "exclude_entity_types": [
    "text"
  ]
}
{}
{}
POST /api/preview/graph/tag_promotions:demote HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "tag_key": "text",
  "tag_type": 1
}
GET /api/preview/graph/tag_promotions HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "tag_promotions": [
    {
      "tag_key": "text",
      "tag_type": 1,
      "include_entity_types": [
        "text"
      ],
      "exclude_entity_types": [
        "text"
      ]
    }
  ]
}