Create an access management tag
POST /v3/tags
Create an access management tag. To create an `access` tag, you must have the access listed in the Granting users access to tag resources documentation. `service` and `user` tags cannot be created upfront. They are created when they are attached for the first time to a resource.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
This action applies only to access management tags.
ghost-tags.create-access-tag
Auditing
Calling this method generates the following auditing event.
global-search-tagging.tag.create
Request
Request Body
CreateTagBody
An array of access management tags to be created.
tag_names
Required *
array
An array of tag names to create
Path Parameters
Query Parameters
account_id
string
The ID of the billing account where the tag must be created.
tag_type
string
The type of the tags you want to create. The only allowed value is `access`.
Response
200 - The tag was created successfully.
results
array
Array of results of a create_tag request.
400 - Bad request
errors
array
Detailed errors list
401 - Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
errors
array
Detailed errors list
429 - Too Many Requests
default - System problem or unexpected error.
Delete all unused tags
DELETE /v3/tags
Delete the tags that are not attached to any resource.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
This action applies only to access management tags.
ghost-tags.delete-access-tag
Auditing
Calling this method generates the following auditing event.
global-search-tagging.tags.delete
Request
Path Parameters
Query Parameters
providers
string
Select a provider. Supported values are `ghost` and `ims`.
account_id
string
The ID of the billing account to delete the tags for. If it is not set, then it is taken from the authorization token. It is a required parameter if `tag_type` is set to `service`.
tag_type
string
The type of the tag. Supported values are `user`, `service` and `access`. `service` and `access` are not supported for IMS resources (`providers` parameter set to `ims`).
Response
200 - A results page that includes the list of tags that have been deleted.
total_count
integer
The number of tags that have been deleted.
errors
boolean
It is set to true if there is at least one tag operation in error.
items
array
The list of tag operation results.
400 - Bad request
errors
array
Detailed errors list
401 - Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
errors
array
Detailed errors list
429 - Too Many Requests
default - System problem or unexpected error
Delete an unused tag
DELETE /v3/tags/{tag_name}
Delete an existing tag. A tag can be deleted only if it is not attached to any resource.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
This action applies only to access management tags.
ghost-tags.delete-access-tag
Auditing
Calling this method generates the following auditing event.
global-search-tagging.tag.delete
Request
Path Parameters
tag_name
Required *
string
The name of tag to be deleted.
Query Parameters
providers
array
Select a provider. Supported values are `ghost` and `ims`. To delete tags both in Global Search and Tagging and in IMS, use `ghost,ims`
account_id
string
The ID of the billing account to delete the tag for. It is a required parameter if `tag_type` is set to `service`, otherwise it is inferred from the authorization IAM token.
tag_type
string
The type of the tag. Supported values are `user`, `service` and `access`. `service` and `access` are not supported for IMS resources (`providers` parameter set to `ims`).
Response
200 - Success message
results
array
Array of results of a delete_tag request.
400 - Bad request
errors
array
Detailed errors list
401 - Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
errors
array
Detailed errors list
429 - Too Many Requests
default - System problem or unexpected error
Attach tags
POST /v3/tags/attach
Attaches one or more tags to one or more resources. Each resource can have no more than 1000 tags per each 'user' and 'service' type, and no more than 250 'access' tags (which is the account limit).
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
This action applies only to user tags. Because service tags are managed by IBM services. IAM actions do not apply to them.
To attach a `user` tag on a resource, you must have the access listed in the Granting users access to tag resources documentation.
To attach a `service` tag, you must be an authorized service. If that is the case, then you can attach a `service` tag with your registered `prefix` to any resource in any account. The account ID must be set through the `account_id` query parameter.
To attach an `access` tag, you must be the resource administrator within the account. You can attach only `access` tags that already exist.
In the case you want to replace all the list of user tags attached, you must have both the accesses to attach and detach user tags to the resource.
In the case you want to replace all the list of access tags attached, you must have both the accesses to attach and detach access tags to the resource.
global-search-tagging.tag.attach-user-tagglobal-search-tagging.tag.attach-access-tagglobal-search-tagging.tag.detach-user-tagglobal-search-tagging.tag.detach-access-tag
Auditing
Calling this method generates the following auditing event.
<serviceName>.tag.attach
Request
Request Body
AttachTagRequest
Array of tag names and list of resource IDs on which the tags should be attached or a valid Global Search string that dynamically identifies the resources to attach tags to. In that case the query cannot resolve to more than 100 resources, otherwise the entire operation will fail. The caller must have the permission to manage tags on those resources. The operation will fail for the other resources and a specific error is returned in the operation response. For resources that are onboarded to Global Search and Tagging, the resource ID is the CRN; for IMS resources, it is the IMS ID. The maximum number of resource IDs where the tag will be attached is 100. You can specify up to 100 tags to be attached.
tag_name
string
The name of the tag to attach
tag_names
array
An array of tag names to attach
resources
ResourceList
List of resources on which the tagging operation operates on
query
QueryString
A valid Global Search string.
query_string
Required *
string
The Lucene-formatted query string
Path Parameters
Query Parameters
account_id
string
The ID of the billing account of the tagged resource. It is a required parameter if `tag_type` is set to `service`. Otherwise, it is inferred from the authorization IAM token.
tag_type
string
The type of the tag. Supported values are `user`, `service` and `access`. `service` and `access` are not supported for IMS resources.
replace
boolean
Flag to request replacement of all attached tags. Set `true` if you want to replace all tags attached to the resource with the current ones. Default value is false.
update
boolean
Flag to request update of attached tags in the format `key:value`. Here's how it works for each tag in the request body: If the tag to attach is in the format `key:value`, the System will atomically detach all existing tags starting with `key:` and attach the new `key:value` tag. If no such tags exist, a new `key:value` tag will be attached. If the tag is not in the `key:value` format (e.g., a simple label), the System will attach the label as usual. The update query parameter is available for user and access management tags, but not for service tags.
Response
200 - The array of tag attach operations result
results
array
Array of results of an attach_tag or detach_tag request.
400 - Bad request
errors
array
Detailed errors list
401 - Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
errors
array
Detailed errors list
429 - Too Many Requests
default - System problem or unexpected error
Detach tags
POST /v3/tags/detach
Detaches one or more tags from one or more resources.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
This action applies only to user tags. Because service tags are managed by IBM services, IAM actions do not apply to them.
To detach a `user` tag on a resource you must have the permissions listed in the Granting users access to tag resources documentation.
To detach a `service` tag, you must be an authorized Service. If that is the case, then you can detach a `service` tag with your registered `prefix` from any resource in any account. The account ID must be set through the `account_id` query parameter.
To detach an `access` tag, you must be the resource administrator within the account.
global-search-tagging.tag.detach-user-tagglobal-search-tagging.tag.detach-access-tag
Auditing
Calling this method generates the following auditing event.
<serviceName>.tag.detach
Request
Request Body
DetachTagRequest
Array of tag names and the list of resources to detach tags from, or a valid Global Search string that dynamically identifies the resources to detach tags from. In that case the query cannot resolve to more than 100 resources, otherwise the entire operation will fail. The caller must have the permission to manage tags on those resources. The operation will fail for the other resources and a specific error is returned in the operation response.
tag_name
string
The name of the tag to detach
tag_names
array
An array of tag names to detach
resources
ResourceList
List of resources on which the tagging operation operates on
query
QueryString
A valid Global Search string.
query_string
Required *
string
The Lucene-formatted query string
Path Parameters
Query Parameters
account_id
string
The ID of the billing account of the untagged resource. It is a required parameter if `tag_type` is set to `service`, otherwise it is inferred from the authorization IAM token.
tag_type
string
The type of the tag. Supported values are `user`, `service` and `access`. `service` and `access` are not supported for IMS resources.
Response
200 - The array of tag detach operations results.
results
array
Array of results of an attach_tag or detach_tag request.
400 - Bad request
errors
array
Detailed errors list
401 - Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
errors
array
Detailed errors list