Create a target

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.create
  • atracker.enterprise-target.create (used when managed_by=enterprise)

Auditing

Calling this method generates the following auditing event.

  • atracker.target.create
  • atracker.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 -

List targets

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 details of a target

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 -

Update a target

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.update
  • atracker.enterprise-target.update (used when managed_by=enterprise)

Auditing

Calling this method generates the following auditing event.

  • atracker.target.update
  • atracker.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.delete
  • atracker.enterprise-target.delete (used when managed_by=enterprise)

Auditing

Calling this method generates the following auditing event.

  • atracker.target.delete
  • atracker.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 -

Create a route

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.create
  • atracker.enterprise-route.create (used when managed_by=enterprise)

Auditing

Calling this method generates the following auditing event.

  • atracker.route.create
  • atracker.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 -

List routes

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 details of a route

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 -

Update a route

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.update
  • atracker.enterprise-route.update (used when managed_by=enterprise)

Auditing

Calling this method generates the following auditing event.

  • atracker.route.update
  • atracker.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.delete
  • atracker.enterprise-route.delete (used when managed_by=enterprise)

Auditing

Calling this method generates the following auditing event.

  • atracker.route.delete
  • atracker.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 -

Modify settings

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.

400 -

401 -

403 -

500 -