POST /api/v2/targets
Creates a target that includes information about the endpoint and the credentials required to write to that target. You can send your logs from all regions to a single target, different targets or multiple targets. One target per region is not required. You can define up to 16 targets per account.
Enterprise management: Optionally set `managed_by: "enterprise"` in the request body to create an enterprise-managed target. the `managed_by` value is immutable after creation and you cannot mingle account-managed and enterprise-managed resources
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.target.createatracker.enterprise-target.create (used when managed_by=enterprise)
Auditing
Calling this method generates the following auditing event.
atracker.target.createatracker.enterprise-target.create (emitted when managed_by=enterprise)
Request
Request Body
TargetPrototype
name
Required *
string
The name of the target. The name must be 1000 characters or less, and cannot include any special characters other than `(space) - . _ :`. Do not include any personal identifying information (PII) in any resource names.
target_type
Required *
string
The type of the target. It can be cloud_object_storage, event_streams, or cloud_logs. Based on this type you must include cos_endpoint, eventstreams_endpoint or cloudlogs_endpoint.
cos_endpoint
CosEndpointPrototype
Property values for a Cloud Object Storage Endpoint in requests.
endpoint
Required *
string
The host name of the Cloud Object Storage endpoint.
target_crn
Required *
string
The CRN of the Cloud Object Storage instance.
bucket
Required *
string
The bucket name under the Cloud Object Storage instance.
api_key
string
The IAM API key that has writer access to the Cloud Object Storage instance. This credential is masked in the response. This is required if service_to_service is not enabled.
service_to_service_enabled
boolean
Determines if IBM Cloud Activity Tracker Event Routing has service to service authentication enabled. Set this flag to true if service to service is enabled and do not supply an apikey.
eventstreams_endpoint
EventstreamsEndpointPrototype
Property values for an Event Streams Endpoint in requests.
target_crn
Required *
string
The CRN of the Event Streams instance.
brokers
Required *
array
List of broker endpoints.
topic
Required *
string
The messsage hub topic defined in the Event Streams instance.
api_key
string
The user password (api key) for the message hub topic in the Event Streams instance. This is required if service_to_service is not enabled.
service_to_service_enabled
boolean
Determines if IBM Cloud Activity Tracker Event Routing has service to service authentication enabled. Set this flag to true if service to service is enabled and do not supply an apikey.
cloudlogs_endpoint
CloudLogsEndpointPrototype
Property values for an IBM Cloud Logs endpoint in requests.
target_crn
Required *
string
The CRN of the IBM Cloud Logs instance.
region
string
Include this optional field if you want to create a target in a different region other than the one you are connected.
managed_by
string
Identifies who manages this target. Optional at create time. If set to `enterprise`, the target becomes enterprise-managed and can only be modified by identities authorized for the enterprise actions. If omitted or set to `account`, the target is managed by the child account. This value is immutable after creation.
Response
201 - The COS target was successfully created for this region.
id
string
The uuid of the target resource.
name
string
The name of the target resource.
crn
string
The crn of the target resource.
target_type
string
The type of the target.
region
string
Included this optional field if you used it to create a target in a different region other than the one you are connected.
cos_endpoint
CosEndpoint
Property values for a Cloud Object Storage Endpoint in responses.
eventstreams_endpoint
EventstreamsEndpoint
Property values for the Event Streams Endpoint in responses.
cloudlogs_endpoint
CloudLogsEndpoint
Property values for the IBM Cloud Logs endpoint in responses.
write_status
WriteStatus
The status of the write attempt to the target with the provided endpoint parameters.
created_at
string
The timestamp of the target creation time.
updated_at
string
The timestamp of the target last updated time.
message
string
An optional message containing information about the target.
api_version
integer
The API version of the target.
managed_by
string
Identifies who manages the target.
400 -
401 -
403 -
422 -
429 -
500 -
GET /api/v2/targets
List all targets that are defined for your account.
Enterprise management - The response will include the `managed_by` field. - The `managed_by` attribute is immutable; it cannot be changed after creation. This endpoint only reads/returns targets and does not modify their state.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.target.list
Auditing
Calling this method generates the following auditing event.
atracker.target.list
Request
Path Parameters
Query Parameters
region
string
Limit the query to the specified region
Response
200 - List all targets defined.
targets
array
A list of target resources.
400 -
401 -
403 -
429 -
500 -
GET /api/v2/targets/{id}
Retrieve the configuration details of a target.
Enterprise management - The response will include a `managed_by` field indicating if the target is managed by `"enterprise"` or `"account"`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.target.get
Auditing
Calling this method generates the following auditing event.
atracker.target.get
Request
Response
200 - Retrieve a target.
id
string
The uuid of the target resource.
name
string
The name of the target resource.
crn
string
The crn of the target resource.
target_type
string
The type of the target.
region
string
Included this optional field if you used it to create a target in a different region other than the one you are connected.
cos_endpoint
CosEndpoint
Property values for a Cloud Object Storage Endpoint in responses.
eventstreams_endpoint
EventstreamsEndpoint
Property values for the Event Streams Endpoint in responses.
cloudlogs_endpoint
CloudLogsEndpoint
Property values for the IBM Cloud Logs endpoint in responses.
write_status
WriteStatus
The status of the write attempt to the target with the provided endpoint parameters.
created_at
string
The timestamp of the target creation time.
updated_at
string
The timestamp of the target last updated time.
message
string
An optional message containing information about the target.
api_version
integer
The API version of the target.
managed_by
string
Identifies who manages the target.
400 -
401 -
403 -
404 -
429 -
500 -
PUT /api/v2/targets/{id}
Update the configuration details of a target.
Enterprise management - The `managed_by` attribute is immutable and cannot be modified. - Enterprise-managed targets can only be updated by identities authorized for enterprise target actions.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.target.updateatracker.enterprise-target.update (used when managed_by=enterprise)
Auditing
Calling this method generates the following auditing event.
atracker.target.updateatracker.enterprise-target.update (emitted when managed_by=enterprise)
Request
Request Body
UpdateTargetPrototype
name
string
The name of the target. The name must be 1000 characters or less, and cannot include any special characters other than `(space) - . _ :`. Do not include any personal identifying information (PII) in any resource names.
cos_endpoint
CosEndpointPrototype
Property values for a Cloud Object Storage Endpoint in requests.
endpoint
Required *
string
The host name of the Cloud Object Storage endpoint.
target_crn
Required *
string
The CRN of the Cloud Object Storage instance.
bucket
Required *
string
The bucket name under the Cloud Object Storage instance.
api_key
string
The IAM API key that has writer access to the Cloud Object Storage instance. This credential is masked in the response. This is required if service_to_service is not enabled.
service_to_service_enabled
boolean
Determines if IBM Cloud Activity Tracker Event Routing has service to service authentication enabled. Set this flag to true if service to service is enabled and do not supply an apikey.
eventstreams_endpoint
EventstreamsEndpointPrototype
Property values for an Event Streams Endpoint in requests.
target_crn
Required *
string
The CRN of the Event Streams instance.
brokers
Required *
array
List of broker endpoints.
topic
Required *
string
The messsage hub topic defined in the Event Streams instance.
api_key
string
The user password (api key) for the message hub topic in the Event Streams instance. This is required if service_to_service is not enabled.
service_to_service_enabled
boolean
Determines if IBM Cloud Activity Tracker Event Routing has service to service authentication enabled. Set this flag to true if service to service is enabled and do not supply an apikey.
cloudlogs_endpoint
CloudLogsEndpointPrototype
Property values for an IBM Cloud Logs endpoint in requests.
target_crn
Required *
string
The CRN of the IBM Cloud Logs instance.
Response
200 - The target was successfully updated.
id
string
The uuid of the target resource.
name
string
The name of the target resource.
crn
string
The crn of the target resource.
target_type
string
The type of the target.
region
string
Included this optional field if you used it to create a target in a different region other than the one you are connected.
cos_endpoint
CosEndpoint
Property values for a Cloud Object Storage Endpoint in responses.
eventstreams_endpoint
EventstreamsEndpoint
Property values for the Event Streams Endpoint in responses.
cloudlogs_endpoint
CloudLogsEndpoint
Property values for the IBM Cloud Logs endpoint in responses.
write_status
WriteStatus
The status of the write attempt to the target with the provided endpoint parameters.
created_at
string
The timestamp of the target creation time.
updated_at
string
The timestamp of the target last updated time.
message
string
An optional message containing information about the target.
api_version
integer
The API version of the target.
managed_by
string
Identifies who manages the target.
400 -
401 -
403 -
404 -
422 -
429 -
500 -
Delete a target
DELETE /api/v2/targets/{id}
Delete a target.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.target.deleteatracker.enterprise-target.delete (used when managed_by=enterprise)
Auditing
Calling this method generates the following auditing event.
atracker.target.deleteatracker.enterprise-target.delete (emitted when managed_by=enterprise)
Request
Response
200 -
204 - The target is successfully deleted.
400 -
401 -
403 -
404 -
409 - The delete request could not be fulfilled because the target is in use.
status_code
integer
The status code.
trace
string
The transaction-id of the API request.
errors
array
The error array triggered by the API request.
429 -
500 -
Validate a target
POST /api/v2/targets/{id}/validate
Validate a target by checking the credentials to write to the target. The result is included as additional data of the target in the section "write_status".
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.target.update
Auditing
Calling this method generates the following auditing event.
atracker.target.update
Request
Response
200 - The target is successfully updated.
id
string
The uuid of the target resource.
name
string
The name of the target resource.
crn
string
The crn of the target resource.
target_type
string
The type of the target.
region
string
Included this optional field if you used it to create a target in a different region other than the one you are connected.
cos_endpoint
CosEndpoint
Property values for a Cloud Object Storage Endpoint in responses.
eventstreams_endpoint
EventstreamsEndpoint
Property values for the Event Streams Endpoint in responses.
cloudlogs_endpoint
CloudLogsEndpoint
Property values for the IBM Cloud Logs endpoint in responses.
write_status
WriteStatus
The status of the write attempt to the target with the provided endpoint parameters.
created_at
string
The timestamp of the target creation time.
updated_at
string
The timestamp of the target last updated time.
message
string
An optional message containing information about the target.
api_version
integer
The API version of the target.
managed_by
string
Identifies who manages the target.
400 -
401 -
403 -
404 -
429 -
500 -
POST /api/v2/routes
Create a route to define the rule that specifies how to manage auditing events.
Enterprise management The `managed_by` value is immutable and you cannot mingle account-managed and enterprise-managed resources.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.route.createatracker.enterprise-route.create (used when managed_by=enterprise)
Auditing
Calling this method generates the following auditing event.
atracker.route.createatracker.enterprise-route.create (emitted when managed_by=enterprise)
Request
Request Body
RoutePrototype
name
Required *
string
The name of the route. The name must be 1000 characters or less and cannot include any special characters other than `(space) - . _ :`. Do not include any personal identifying information (PII) in any resource names.
rules
Required *
array
Routing rules that will be evaluated in their order of the array.
managed_by
string
Identifies who manages this route. Optional at create time. The managed_by value is immutable and you cannot mingle account-managed and enterprise-managed resources.
Response
201 - A route is successfully created for this region.
id
string
The uuid of the route resource.
name
string
The name of the route.
crn
string
The crn of the route resource.
version
integer
The version of the route.
rules
array
The routing rules that will be evaluated in their order of the array. Once a rule is matched, the remaining rules in the route definition will be skipped.
created_at
string
The timestamp of the route creation time.
updated_at
string
The timestamp of the route last updated time.
api_version
integer
The API version of the route.
message
string
An optional message containing information about the route.
managed_by
string
Present when the route is enterprise-managed (`managed_by: enterprise`).
400 -
401 -
403 -
422 -
429 -
500 -
GET /api/v2/routes
List the route that is configured for an account.
Enterprise management - The response includes the `managed_by` field. - The `managed_by` value is immutable.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.route.list
Auditing
Calling this method generates the following auditing event.
atracker.route.list
Request
Response
200 - List routes defined.
routes
array
A list of route resources.
400 -
401 -
403 -
429 -
500 -
GET /api/v2/routes/{id}
Get the configuration details of a route.
Enterprise management - The response includes the `managed_by:` field. - The `managed_by` value is immutable.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.route.get
Auditing
Calling this method generates the following auditing event.
atracker.route.get
Request
Response
200 - Retrieve a route.
id
string
The uuid of the route resource.
name
string
The name of the route.
crn
string
The crn of the route resource.
version
integer
The version of the route.
rules
array
The routing rules that will be evaluated in their order of the array. Once a rule is matched, the remaining rules in the route definition will be skipped.
created_at
string
The timestamp of the route creation time.
updated_at
string
The timestamp of the route last updated time.
api_version
integer
The API version of the route.
message
string
An optional message containing information about the route.
managed_by
string
Present when the route is enterprise-managed (`managed_by: enterprise`).
400 -
401 -
403 -
404 -
429 -
500 -
PUT /api/v2/routes/{id}
Update the configuration details of a route.
Enterprise management The `managed_by` value is immutable and you cannot mingle account-managed and enterprise-managed resources.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.route.updateatracker.enterprise-route.update (used when managed_by=enterprise)
Auditing
Calling this method generates the following auditing event.
atracker.route.updateatracker.enterprise-route.update (emitted when managed_by=enterprise)
Request
Request Body
RoutePrototype
name
Required *
string
The name of the route. The name must be 1000 characters or less and cannot include any special characters other than `(space) - . _ :`. Do not include any personal identifying information (PII) in any resource names.
rules
Required *
array
Routing rules that will be evaluated in their order of the array.
managed_by
string
Identifies who manages this route. Optional at create time. The managed_by value is immutable and you cannot mingle account-managed and enterprise-managed resources.
Response
200 - The route was successfully updated.
id
string
The uuid of the route resource.
name
string
The name of the route.
crn
string
The crn of the route resource.
version
integer
The version of the route.
rules
array
The routing rules that will be evaluated in their order of the array. Once a rule is matched, the remaining rules in the route definition will be skipped.
created_at
string
The timestamp of the route creation time.
updated_at
string
The timestamp of the route last updated time.
api_version
integer
The API version of the route.
message
string
An optional message containing information about the route.
managed_by
string
Present when the route is enterprise-managed (`managed_by: enterprise`).
400 -
401 -
403 -
404 -
422 -
429 -
500 -
Delete a route
DELETE /api/v2/routes/{id}
Deletes a route.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.route.deleteatracker.enterprise-route.delete (used when managed_by=enterprise)
Auditing
Calling this method generates the following auditing event.
atracker.route.deleteatracker.enterprise-route.delete (emitted when managed_by=enterprise)
Request
Response
204 - The route is successfully deleted.
400 -
401 -
403 -
404 -
429 -
500 -
Get settings
GET /api/v2/settings
Get information about the current settings including default targets.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.setting.get
Auditing
Calling this method generates the following auditing event.
atracker.setting.get
Request
Response
200 - Get atracker service settings
default_targets
array
The target ID List. In the event that no routing rule causes the event to be sent to a target, these targets will receive the event. Enterprise-managed targets are not supported.
permitted_target_regions
array
If present then only these regions may be used to define a target.
metadata_region_primary
string
To store all your meta data in a single region.
metadata_region_backup
string
To store all your meta data in a backup region.
private_api_endpoint_only
boolean
If you set this true then you cannot access api through public network.
api_version
integer
API version used for configuring IBM Cloud Activity Tracker Event Routing resources in the account.
message
string
An optional message containing information about the audit log locations.
400 -
401 -
403 -
429 -
500 -
PUT /api/v2/settings
Modify the current settings such as default targets, permitted target regions, metadata region primary and secondary.
Enterprise management - Default targets must be account-managed. Enterprise-managed targets (`managed_by: enterprise`) cannot be set as default targets and will be rejected.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.setting.set
Auditing
Calling this method generates the following auditing event.
atracker.setting.set
Request
Request Body
SettingsPrototype
default_targets
array
The target ID List. In the event that no routing rule causes the event to be sent to a target, these targets will receive the event. Enterprise-managed targets are not supported.
permitted_target_regions
array
If present then only these regions may be used to define a target.
metadata_region_primary
Required *
string
To store all your meta data in a single region.
metadata_region_backup
string
To store all your meta data in a backup region.
private_api_endpoint_only
Required *
boolean
If you set this true then you cannot access api through public network.
Response
201 - The settings is successfully modified.
default_targets
array
The target ID List. In the event that no routing rule causes the event to be sent to a target, these targets will receive the event. Enterprise-managed targets are not supported.
permitted_target_regions
array
If present then only these regions may be used to define a target.
metadata_region_primary
string
To store all your meta data in a single region.
metadata_region_backup
string
To store all your meta data in a backup region.
private_api_endpoint_only
boolean
If you set this true then you cannot access api through public network.
api_version
integer
API version used for configuring IBM Cloud Activity Tracker Event Routing resources in the account.
message
string
An optional message containing information about the audit log locations.
400 - The request could not be understood due to malformed syntax.
status_code
integer
The status code.
trace
string
The transaction-id of the API request.
errors
array
The error array triggered by the API request.
401 -
403 -
429 -
500 -
Query Destinations
POST /api/v2/destinations/query
Query target destinations for a given set of cloud resources.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
atracker.destination.search
Auditing
Calling this method generates the following auditing event.
atracker.destination.search
Request
Request Body
DestinationsQueryPrototype
crns
Required *
array
List of resource CRNs that will be queried.
Response
200 - Query target destinations for a given set of cloud resources.
destinations
DestinationsMap
Key is the resource CRN. Value is an array of target destinations for each requested resource CRN.