Manage Tags

The following Britive API methods can be used to manage tags and perform relevant operations.

1. Create a Tag

The POST method creates a tag in the system. Enter the required name and description as parameters in this request.

Request Example

An example POST request for creating a tag is shown here.

curl --location --request POST '{{url}}/api/user-tags' \
--header 'Authorization: TOKEN {{apiToken}}' \
--data-raw '{
    "name": "DocTestTag",
    "description": "DocTestTag"
}'

Response Example 

An example response of the POST request for creating a tag is shown here.

{
  "userTagId" : "7twt0mgi0msiajm4zt5t",
  "name" : "DocTestTag",
  "status" : "Active",
  "description" : "DocTestTag",
  "created" : "2023-03-22T10:46:39Z",
  "modified" : null,
  "external" : false,
  "membershipRule" : false,
  "userTagUserBeans" : [ ],
  "userTagIdentityProviders" : [ {
    "identityProvider" : {
      "id" : "1HhvrKWjoFPXvOcbJSDx",
      "name" : "Britive",
      "description" : "Default Identity Provider",
      "type" : "DEFAULT",
      "scimProvider" : "Generic",
      "ssoProvider" : "Generic",
      "scimEnabled" : false,
      "samlMetadata" : null,
      "ssoConfig" : null,
      "mfaEnabled" : false,
      "mfaRootUserEnabled" : false,
      "apiToken" : null,
      "userAttributeScimMappings" : [ ]
    },
    "externalId" : null
  } ],
  "attributeCriteriaBeans" : [ ],
  "userCount" : 0
}

2. Update a Tag

The PATCH method updates a tag in the system, as indicated by the userTagID provided in the request. Enter the required name and description as parameters in the request. 

Request Example

An example PATCH request for updating a tag is shown here.

curl --location --request PATCH '{{url}}/api/user-tags' \
--header 'Authorization: TOKEN {{apiToken}}' \
--data-raw '{
    "userTagId": "{{userTagID}}",
    "name": "Dev Admins",
    "description" : "Administrators"
}'

Response Example 

An example response of the PATCH request for updating a tag is shown here.

{
  "userTagId" : "7j4uouyqnl7e1gy3fh0n",
  "name" : "Admins1",
  "status" : "Active",
  "description" : "No Description",
  "userTagIdentityProviders" : [ {
    "identityProvider" : {
      "id" : "1HhvrKWjoFPXvOcbJSDx",
      "name" : "Britive",
      "description" : "Default Identity Provider",
      "type" : "DEFAULT",
      "scimProvider" : "Generic",
      "ssoProvider" : "Generic",
      "scimEnabled" : false,
      "samlMetadata" : null,
      "ssoConfig" : null,
      "mfaEnabled" : false,
      "mfaRootUserEnabled" : false,
      "userAttributeScimMappings" : [],
      "apiToken" : null
    },
    "externalId" : null
  } ],
  "external" : false,
  "userCount" : 0
}

3. Details of all Tags   

This API retrieves details of all tags available in the system. The API returns data in pages and multiple API calls have to be made to return the complete list. The API returns the total number of records that can be used to calculate the number of pages. 

Request Parameters

The request parameters used in this method are shown in the following table:

Request Example

An example GET request for retrieving the details of all the tags is shown here.

curl --location --request GET '{{url}}/api/user-tags?page=0&size=20&sort=name,asc&filter=status%20eq%20Active' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the GET request for retrieving the list of all tags in the system is shown here.

{
    "count": 1064,
    "page": 0,
    "size": 20,
    "sort": "name: ASC",
    "filter": "status eq Active",
    "data": [
        {
            "userTagId": "AR7IYvLY9o6qqOEQEmLV",
            "name": "Tag1",
            "description": "No Description",
            "status": "Active",
            "userCount": 3,
            "created": null,
            "modified": null,
            "userTagIdentityProviders": [],
            "external": false
        }
    ]
}

(Deprecated) Details of all Tags

The GET method retrieves the details of all the tags available in the system.  

Request Example

An example GET request for retrieving the details of all the tags is shown here.

curl --location --request GET '{{url}}/api/user-tags' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the GET request for retrieving the details of all tags in the system is shown here.

[
    {
        "userTagId": "02j4ms3nmlyv3a0hcfup",
        "name": "Admins",
        "description": "",
        "status": "Active",
        "userCount": 0,
        "userTagIdentityProviders": [
            {
                "identityProvider": {
                    "id": "1HhvrKWjoFPXvOcbJSDx",
                    "name": "Britive",
                    "type": "DEFAULT"
                },
                "externalId": null
            }
        ],
        "external": false
    }
]

4. Details of a Tag

The GET method retrieves the details of a tag, as indicated by the userTagID provided in the request.  

Request Example

An example GET request for retrieving the details of a tag is shown here.

curl --location --request GET '{{url}}/api/user-tags/{{userTagID}}' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the GET request for retrieving the details of a tag is shown here.

{
    "userTagId": "02j4ms3nmlyv3a0hcfup",
    "name": "Admins",
    "description": "",
    "status": "Active",
    "userCount": 0,
    "userTagIdentityProviders": [
        {
            "identityProvider": {
                "id": "1HhvrKWjoFPXvOcbJSDx",
                "name": "Britive",
                "type": "DEFAULT"
            },
            "externalId": null
        }
    ],
    "external": false
}

5. Details of all Users of a Tag 

This API retrieves the details of all users assigned to a tag, as indicated by tagID provided in the request. The API returns data in pages and multiple API calls have to be made to return the complete list. The API returns the total number of records that can be used to calculate the number of pages. 

Request Parameters

The request parameters used in this method are shown in the following table:

Request Example

An example GET request for retrieving all the users assigned to a tag is shown here.

curl --location --request GET '{{url}}/api/user-tags/o96sdb8f5181hzr2rhw1/users?page=0&size=20' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the GET request for retrieving all the users assigned to a tag is shown here.

{
    "count": 3,
    "page": 0,
    "size": 20,
    "sort": null,
    "filter": null,
    "data": [
        {
            "adminRoles": [
                {
                    "name": "TenantAdmin",
                    "displayName": "Admin"
                }
            ],
            "type": "User",
            "created": "2019-04-03T15:46:33Z",
            "modified": "2019-10-18T07:54:38Z",
            "email": "bob@britive.com",
            "username": "bob1",
            "firstName": "Bob",
            "lastName": "Smith",
            "name": "Bob Smith",
            "externalId": null,
            "mobile": null,
            "phone": null,
            "identityProvider": {
                "id": "1HhvrKWjoFPXvOcbJSDx",
                "name": "Britive",
                "type": "DEFAULT"
            },
            "mappedAccounts": [],
            "external": false,
            "status": "active",
            "userId": "tVvgWNatCHgfLbZMWEdU"
        }
    ]
}

(Deprecated) Details of all Users of a Tag

The GET method returns all the users assigned to a tag, as indicated by the userTagID provided in the request. 

Request Example

An example GET request for retrieving all the users assigned to a tag is shown here.

curl --location --request GET '{{url}}/api/user-tags/{{userTagID}}/users?filter=assigned' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the GET request for retrieving all the users assigned to a tag is shown here.

{
    "adminRoles": null,
    "type": "User",
    "email": "user@company.com",
    "username": "user",
    "externalId": null,
    "identityProvider": null,
    "mappedAccounts": [],
    "external": false,
    "status": "active",
    "userId": "47S7Pl0mQvlqMUBulgRw"
}

6. Details of Available Users for a Tag

The GET method returns all the users available in the system and can be possibly added to a tag, as indicated by the userTagID provided in the request. The request parameter required is filter and its value is available.

Request Example

An example GET request for retrieving all the available users, which can be possibly added to a tag is shown here.

curl --location --request GET '{{url}}/api/user-tags/{{userTagID}}/users?filter=available' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the GET request for retrieving all the available users is shown here.

{
    "adminRoles": null,
    "type": "User",
    "email": "user@company.com",
    "username": "user",
    "externalId": null,
    "identityProvider": null,
    "mappedAccounts": [],
    "external": false,
    "status": "active",
    "userId": "47S7Pl0mQvlqMUBulgRw"
}

7. Add a User to a Tag

The POST method adds a user to a tag, as indicated by the userTagID provided in the request.  

Request Example

An example POST request for adding a user to a tag is shown here.

curl --location --request POST '{{url}}/api/user-tags/{{userTagId}}/users/{{userId}}' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the POST request for adding a user to a tag is shown here.

{
  "status" : "active",
  "adminRoles" : [ ],
  "type" : "User",
  "created" : "2022-05-18T13:26:41Z",
  "modified" : null,
  "email" : "user@company.com",
  "username" : "user",
  "firstName" : "User",
  "lastName" : "Test",
  "name" : "User Test",
  "externalId" : null,
  "mobile" : null,
  "phone" : null,
  "identityProvider" : {
    "id" : "1HhvrKWjoFPXvOcbJSDx",
    "name" : "Britive",
    "type" : "DEFAULT"
  },
  "mappedAccounts" : [ ],
  "external" : false,
  "userId" : "g9mbruluggn4au04vbcr"
}

8. Remove a User from a Tag

The DELETE method removes a user from a tag, as indicated by the userTagID provided in the request.   

Request Example

An example DELETE request for removing a tag is shown here.

curl --location --request DELETE '{{url}}/api/user-tags/{{userTagID}}/users/{{userID}}' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example  

The response only has headers.

9. Enable a Tag

The POST method enables a tag, as indicated by the userTagID provided in the request.     

Request Example

An example POST request for enabling a tag is shown here.

curl --location --request POST '{{url}}/api/user-tags/{{userTagID}}/enabled-statuses' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of POST request for enabling a tag is shown here.

{
    "userTagId": "02j4ms3nmlyv3a0hcfup",
    "name": "Admins",
    "description": "",
    "status": "Active",
    "userCount": 0,
    "userTagIdentityProviders": [
        {
            "identityProvider": {
                "id": "1HhvrKWjoFPXvOcbJSDx",
                "name": "Company",
                "type": "DEFAULT"
            },
            "externalId": null
        }
    ],
    "external": false
}

10. Disable a Tag

The POST method disables a tag, as indicated by the userTagID provided in the request.   

Request Example

An example POST request for disabling a tag is shown here.

curl --location --request POST '{{url}}/api/user-tags/{{userTagID}}/disabled-statuses' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the POST request for disabling a tag is shown here.

{
    "userTagId": "02j4ms3nmlyv3a0hcfup",
    "name": "Admins",
    "description": "",
    "status": "Active",
    "userCount": 0,
    "userTagIdentityProviders": [
        {
            "identityProvider": {
                "id": "1HhvrKWjoFPXvOcbJSDx",
                "name": "Britive",
                "type": "DEFAULT"
            },
            "externalId": null
        }
    ],
    "external": false
}

11. Delete a Tag

The DELETE method deletes a tag in the system, as indicated by the userTagID provided in the request.   

Request Example

An example DELETE request for deleting a tag is shown here.

curl --location --request DELETE '{{url}}/api/user-tags/{{userTagID}}/disabled-statuses' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

The tag is deleted. Note that the response only has headers.

12. Add Attribute Criteria

The POST method adds attribute criteria for a given tag, as indicated by the tagID provided in the request.   

Request Example

curl --location --request GET '{{url}}/api/user-tags/{{tagID}}/attribute-criteria \
--header 'Authorization: TOKEN {{apiToken}}'[
{
   attributeId: "Ogetw83Ku7GI9VikKryx", 
   operator: "contains", 
   value: "Doc"
}]

Response Example

[ {
  "id" : null,
  "attributeId" : "Ogetw83Ku7GI9VikKryx",
  "operator" : "contains",
  "value" : "Doc"
} ]

Status Code

13. Update attribute Criteria

The PATCH method updates attribute criteria for a given tag, as indicated by the tagID provided in the request.   

Request Example

[
    {
        "id": 12,
        "attributeId": "kd05OnAwWtR0Sjkw5zcI",
        "operator": "is",
        "value": "updatedagain"
    },
    {
        "attributeId": "kd05OnAwWtR0Sjkw5zcJ",
        "operator": "is",
        "value": "test"
    }
]

Response Example

The response only has headers.

14. Details of all users matching a particular criteria

This API retrieves the details of all users matching a particular criteria assigned to a tag, as indicated by tagID provided in the request. 

Request Parameters

The request parameters used in this method are shown in the following table:

Request Example

An example GET request for retrieving all the users assigned to a tag is shown here.

Response Example

{
  "count" : 1,
  "page" : 0,
  "size" : 20,
  "sort" : null,
  "filter" : null,
  "data" : [ {
    "status" : "active",
    "adminRoles" : [ ],
    "type" : "User",
    "created" : "2022-04-20T10:01:06Z",
    "modified" : null,
    "userTags" : [ ],
    "email" : "user@company.com",
    "username" : "docapprover",
    "firstName" : "Doc",
    "lastName" : "Approver",
    "name" : "Doc Approver",
    "externalId" : null,
    "mobile" : null,
    "phone" : null,
    "identityProvider" : {
      "id" : "1HhvrKWjoFPXvOcbJSDx",
      "name" : "CoName",
      "type" : "DEFAULT"
    },
    "mappedAccounts" : [ ],
    "rootUser" : false,
    "external" : false,
    "userId" : "855hx1okg1y9t6d4pi19"
  } ]
}

Status Code