Guide — Endpoint Tags

Overview¶

You can manage endpoint tags using the Endpoint Tags API. Tags are useful for:

Organizing endpoints by category
Filtering and searching for endpoints based on tag in Sophos Central.

This API allows tag management for a single tenant at a time.

Requirements¶

You must have a set of API credentials (service principal) to call the Endpoint Tags API. For more information, refer to the appropriate quick start guide:

Sophos Partners: Read the Partner Getting Started guide first.

Enterprise customers: If you use Sophos Enterprise to manage multiple tenants, read the Organization Getting Started guide first.

Other customers: Read the Tenant Getting Started guide first.

You can make the API calls in the next few sections using cUrl. Follow the instructions on cUrl's website to install this tool.

Each cUrl command in the rest of this guide assumes you replace the following variables:

<tenant-id>: The ID of the tenant you want to query.
<jwt>: The JWT access token returned when the IDP authenticates the service principal.
<data-region>: The regional in which the tenant data is located. To understand these terms, read the appropriate Getting Started guide.

Terminology¶

Tags are labels you can assign to endpoints to help organize your devices. Tags consist of:

Tag Key: A string identifier. Each tag key can only be used once per endpoint.
Tag Value: An optional string value that represents a specific value for a key.

If your tag consists of a key and a value, they will be separated by a colon when displayed.

Examples of tags:¶

Department:Engineering
Location: London
Project: Artemis
VIP

Assign and unassign tags¶

Call this API to assign new tags to endpoints or unassign existing tags:

POST /endpoint/v1/tags/assignment

The request body allows you to specify which endpoints to modify and which tags to assign or unassign:

{
    "entityIds": [
        "17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11",
        "28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12"
    ],
    "assign": [
        {
            "key": "Department",
            "value": "Engineering"
        },
        {
            "key": "VIP",
            "value": ""
        }
    ],
    "unassign": [
        {
            "key": "Location",
            "value": "Old Office"
        },
        {
            "key": "project",
            "value": "Legacy System"
        }
    ]
}

The API processes all requested operations and returns a response indicating success or failure for each endpoint:

Success Response (all operations succeeded):¶

{
    "items": [
        "17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11",
        "28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12"
    ]
}

Partial Failure Response (some operations failed):¶

If the endpoint 28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12 already had a tag with the Department key then the request will respond with a partial failure.

{
    "items": [
        "17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11"
    ],
    "errors": [
        {
            "entityId": "28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12",
            "status": "partial",
            "assigned": [
                {
                    "key": "VIP",
                    "value": ""
                }
            ],
            "unassigned": [
                {
                    "key": "Location",
                    "value": "Old Office"
                }
            ],
            "tagErrors": [
                {
                    "tag": {
                        "key": "Department",
                        "value": "Engineering"
                    },
                    "operation": "assign",
                    "code": "TAG_KEY_CONFLICT",
                    "message": "Tag key 'Department' already exists with value 'Sales'"
                }
            ]
        }
    ]
}

Endpoint 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11 was processed successfully.

The API was able to assign VIP and unassign Location from 28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12 but was unable to assign Department:Engineering.

See Error Handling for more information about partial failure responses.

Tag Objects¶

Tags are simple key-value pairs. They have the following structure:

{
    "key": "Department",        // Tag key (1-40 characters, no colons)
    "value": "Engineering"      // Tag value (0-40 characters, no colons)
}

Tag Key Requirements:¶

Must be 1-40 characters long.
Cannot contain colons (:).

Tag Value Requirements:¶

Must be 0-40 characters long (empty values allowed).
Cannot contain colons (:).

{
    "key": "Department",
    "value": "Engineering"
}

{
    "key": "VIP",
    "value": ""
}

Error Handling¶

The tag assignment API provides detailed error information to help you understand what went wrong. Error codes are prioritized by severity:

Tag Error Codes (in descending priority order):¶

ENTITY_NOT_FOUND: The endpoint does not exist or is not accessible.
- No further operations attempted for this endpoint.
- Usually indicates the endpoint UUID is invalid or the endpoint has been deleted.
WOULD_EXCEED_MAX_TAGS: Assignment would exceed the maximum number of tags allowed (15).
- Each endpoint has a limit on the total number of tags it can have.
- This error prevents the assignment that would exceed this limit.
TAG_KEY_CONFLICT: Tag key already exists with a different value.
- Occurs when trying to assign a tag key that already exists with a different value.
- Each endpoint can only have one value per tag key.
TAG_ALREADY_IN_STATE: Tag is already assigned.
- Informational rather than a critical error.
- Occurs when trying to assign a tag that's already assigned with the same value or when trying to unassign a tag that's already unassigned.

Limitations¶

Rate Limiting: All POST operations are subject to rate limiting. The allowance is based on the number of requests per tenant per minute. When you reach your allowance, you will receive a 429 response.

Request Limits:¶

Maximum 1000 endpoint UUIDs per assignment request.
Maximum 100 tag errors reported per endpoint in error responses.
Maximum page size: 500 items.

Tag Limits:¶

Maximum 15 tags per endpoint
Only one value per tag key per endpoint

Conclusion¶

After reading this guide, you should understand how to use the Endpoint Tags API to:

Assign new tags to endpoints for organization and categorization.
Unassign tags that are no longer needed.
Understand errors and partial failure responses.