IBM Cloud API Docs

Introduction

Last updated: 2024-06-20

As of 28 March 2024 the IBM Log Analysis service is deprecated and will no longer be supported as of 30 March 2025. IBM Cloud Logs Routing will stop supporting logdna targets at the same time and no logs will be routed to these type of targets after that date. You should make sure that you have configured IBM Cloud Logs Routing to direct your logs to another destination before 30 March 2025. Any logdna targets still configured after 30 April 2025 will be removed automatically from your IBM Cloud Logs Routing configuration.

The IBM® Cloud Logs Routing platform service collects application logs and delivers them to a customer-provided logging endpoint.

The IBM Cloud Logs Routing service is available as a regular offering. The only supported log sinks available are IBM Cloud Logs and IBM Log Analysis.

There is a go SDK available to access this service and a terraform provider to support automated setup.

The customer can create (onboard) a tenant for IBM Cloud Logs Routing using either a curl command and the management API described in this documentation, via the IBM Cloud Web Console or by automation using the terraform provider. To collect the logs from the customer's IBM Cloud Kubernetes Service, Red Hat OpenShift on IBM Cloud, IBM® Virtual Servers with Linux or VPC clusters, the log collecting agent must be installed in those environments.

This is a versioned API. To pin your application to a dedicated version add the http header IBM-API-Version with the date in the format YYYY-MM-DD. To use the latest version of the API specify the current day.

Endpoint URLs

The IBM Cloud Logs Routing Services API for tenant creation (onboarding) and tenant deletion (off-boarding) uses site-specific endpoint URLs to register or unregister with the service.

IBM Cloud Logs Routing supports classic infrastructure as well as the Virtual Private Cloud (VPC) endpoint gateway (VPE gateway).

  • Private management endpoint URL for the VPC infrastructure:

    https://management.private.<region>.logs-router.cloud.ibm.com/v1

  • Management endpoint URL for the classic infrastructure:

    https://management.private.<region>.logs-router.cloud.ibm.com:3443/v1

The ingestion endpoint used by the log collecting agent is for IBM-internal use only. It is listed here for reference only.

  • Private ingestion endpoint URL for VPC infrastructure:

    ingester.private.<region>.logs-router.cloud.ibm.com:443/v1/logs/ws

  • Ingestion endpoint URL for classic infrastructure:

    ingester.private.<region>.logs-router.cloud.ibm.com:3443/v1/logs/ws

Replace <region> with the prefix that represents the geographic area where you would like to enable IBM Cloud Logs Routing service. For more information, see Locations.

Example API request

curl -X {request_method}     --header "Authorization: Bearer {bearer_token}"     --header "Accept: application/json"
    --header "X-Trace-ID: A58646E9-F4D5-4327-81B1-AE8D501F35E2"
    [--data "{request_body}"]     "https://management.private.us-south.logs-router.cloud.ibm.com/{method_endpoint}"

Replace {bearer_token}, {request_method}, {method_endpoint} and [optional] {request_body} in this example with the values for your particular API call.

Tracing

An optional header X-Trace-ID is used to trace the transactions performed by the User. Trace ID should be a valid UUID v4 format. The UUID should be unique and added to logs and appropriate database artifacts. The UUID can be used to follow the flow for debugging purposes.

Authentication

Authorization to the IBM Cloud Logs Routing service REST API is enforced by an IBM Cloud® Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Retrieving an access token is supported using an IAM Trusted Profile or IAM API key.

  • To request an access token with a Trusted Profile from within your IBM Cloud Kubernetes Service or Red Hat OpenShift cluster, run the following command:

    curl -X POST \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data "grant_type=urn:ibm:params:oauth:grant-type:cr-token" \
    --data "profile_id={trusted_profile_id}" \
    --data-urlencode "cr_token@{path_to_token}" \
    https://iam.cloud.ibm.com/identity/token

    Replace {trusted_profile_id} and {path_to_token} with the correct values for your environment.

  • To request an access token with an IAM api_key, run the following command:

    curl -X POST \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
    --data "apikey=${IAM_API_KEY}" \
    "https://iam.cloud.ibm.com/identity/token"

    Replace {IAM_API_KEY} with your IAM API key.

The access token is provided in the returned JSON data in the field .access_token.

Auditing

You can use the IBM Cloud Logs service to track and monitor how users, applications and services interact with the IBM Cloud Logs Routing service in IBM Cloud.

For more information about how to monitor activities, see Auditing events for IBM® Cloud Logs Routing.

Error handling

The IBM Cloud Logs Routing Service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response indicates that a parameter validation failed and can occur if required parameters are missing or if any parameter values are invalid. A 401 or 403 response indicates that the incoming request did not contain valid authentication information. A 500 type response indicates an internal server error that is seen in an unexpected error situation.

The IBM Cloud Logs Routing REST APIs return standard HTTP status codes to indicate the success or failure of a request. The format of the response is represented in JSON as follows:

{
    "errors": [
    {
        "code": "not_authorized",
        "message": "The specified token does not have authority to create a tenant."
    }
    ],
    "status_code": 403
}

If an operation cannot be fulfilled, an appropriate 400 or 500 series HTTP response is returned from the server. The operations that are defined in the Reference section describe example errors that might be returned from a failed request. All responses from the Identity Services REST API are in JSON format.

The following table shows the potential error codes the API might return.

HTTP error codes
HTTP Error Code Description Recovery
200 Success The request was successful.
201 Created The resource was successfully created.
204 No Content The request was successful. No response body is provided.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. The token is either missing or expired. Get a new valid token and try again.
403 Forbidden The supplied authentication is not authorized to perform the operation. If this error persists, contact the account owner to check your permissions.
404 Not Found The requested resource can't be found.
412 Precondition failed The content of the If-Match header does not match the expectation in an update request.
415 Bad Request Missing or wrong header
500 Internal error Error that is seen in an unexpected error situation.

Methods

List tenants

List tenants

GET /tenants

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.read

    Mandatory permission to read a tenant ID. It's also part of the role definition named Manager and Reader.

Auditing

Calling this method generates the following auditing event.

When retrieving information about a tenant, the following event is generated.

  • logs-router.tenant.read

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Query Parameters

  • name
    string

    Optional: The name of a tenant

    Possible values: 1 ≤ length ≤ 35, Value must match regular expression [A-F,0-9,-]

  • curl -X GET "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants" --header 'Authorization: Bearer TOKEN' --header 'IBM-API-Version: 2024-06-15'

Response

Response Body

TenantCollection

Response body from a successful list tenants operation

Status Code

  • 200

    Successful operation

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 415

    Wrong Content-Type

  • 500

    Internal server error

Example responses
  • {
  "tenants": [
    {
      "id": "8717DB99-2CFB-4BA6-A033-89C994C2E9F0",
      "created_at": "2024-06-20T18:30:00.143156Z",
      "updated_at": "2024-06-20T18:30:00.143156Z",
      "crn": "crn:v1:bluemix:public:logs-router:eu-de:a/6516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
      "name": "tenant",
      "etag": "\"822b4b5423e225206c1d75666595714a11925cd0f82b229839864443d6c3c049\"",
      "targets": [
        {
          "id": "C1C1C838-A4AC-4BD7-8BC6-3173B272429D",
          "log_sink_crn": "crn:v1:bluemix:public:logdna:eu-de:a/3516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
          "name": "my-logdna-log-sink",
          "etag": "\"c3a43545a7f2675970671ac3a57b8db067a1866b2222e1b950ee8da612e347c6\"",
          "type": "logdna",
          "created_at": "2024-06-20T18:30:00.143156Z",
          "updated_at": "2024-06-20T18:30:00.143156Z",
          "parameters": {
            "host": "www.example.com",
            "port": 8080
          }
        },
        {
          "id": "BFB84FFB-6C2D-4204-A354-829F180B1D8B",
          "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/3516b8fa0a174a71899f5affa4f18d78:42DAB2C2-BEC2-43E3-8E90-F0259087A884::",
          "name": "my-logs-log-sink",
          "etag": "\"c7e475a63f3e9dcd74e432ead845be0821e839e08b087ad5fafd87907d21dbfd\"",
          "type": "logs",
          "created_at": "2024-06-20T18:30:00.143156Z",
          "updated_at": "2024-06-20T18:30:00.143156Z",
          "parameters": {
            "host": "www.example.com",
            "port": 8080
          }
        }
      ]
    }
  ]
}
  • {
  "errors": [
    {
      "code": "failure_getting_authorization_claims",
      "message": "Failed to get authorization claims. Error: token is malformed: token contains an invalid number of segments"
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have authority to create a tenant."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "tenant_ids_not_found",
      "message": "Tenants associated with this account were not found in the database."
    }
  ],
  "status_code": 404
}
  • {
  "errors": [
    {
      "code": "incorrect_or_missing_header",
      "message": "Missing or incorrect header: 'Content-Type'"
    }
  ],
  "status_code": 415
}
  • {
  "errors": [
    {
      "code": "failure_getting_tenant_ids",
      "message": "An error occurred while getting account information from the database."
    }
  ],
  "status_code": 500
}

Create (onboard) a tenant

Create (onboard) a tenant

POST /tenants

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.create

    Mandatory permission to create (onboard) a tenant. It's also part of the role definition named Manager.

Auditing

Calling this method generates the following auditing event.

When creating a tenant, the following event is generated.

  • logs-router.tenant.create

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Request Body

Required*
TenantPrototype

Target type, log-sink endpoint and authentication

Examples: 
{
  "name": "my-logging-tenant",
  "targets": [
    {
      "log_sink_crn": "crn:v1:bluemix:public:logdna:eu-de:a/3516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
      "name": "my-logdna-log-sink",
      "parameters": {
        "host": "www.example.com",
        "port": 8080,
        "access_credential": "an-ingestion-secret"
      }
    },
    {
      "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:42DAB2C2-BEC2-43E3-8E90-F0259087A884::",
      "name": "my-logs-log-sink",
      "parameters": {
        "host": "www.example.com",
        "port": 8080
      }
    }
  ]
}
  • curl -X POST "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants" --header 'Authorization: Bearer TOKEN' --header 'Content-Type: application/json' --header 'IBM-API-Version: 2024-06-15' --data '{
    "name": "tenant",
    "targets": [
        {
            "log_sink_crn": "crn:v1:bluemix:public:logdna:eu-de:a/3516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
            "name": "my-logdna-log-sink",
            "parameters": {
                "host": "www.example.com",
                "port": 8080,
                "access_credential": "an-ingestion-secret" 
            }
        },
        {
            "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:42DAB2C2-BEC2-43E3-8E90-F0259087A884::",
            "name": "my-logs-log-sink",
            "parameters": {
                "host": "www.example.com",
                "port": 8080
            }
        }
    ]
}'

Response

Response Body

Tenant

Full tenant description

Status Code

  • 201

    Successfully created

  • 400

    Bad Request - invalid body

  • 401

    Unauthorized

  • 403

    Forbidden

  • 415

    Wrong Content-Type

  • 500

    Internal server error

Example responses
  • {
  "id": "8717DB99-2CFB-4BA6-A033-89C994C2E9F0",
  "created_at": "2024-06-20T18:30:00.143156Z",
  "updated_at": "2024-06-20T18:30:00.143156Z",
  "crn": "crn:v1:bluemix:public:logs-router:eu-de:a/6516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
  "name": "tenant",
  "etag": "\"822b4b5423e225206c1d75666595714a11925cd0f82b229839864443d6c3c049\"",
  "targets": [
    {
      "id": "C1C1C838-A4AC-4BD7-8BC6-3173B272429D",
      "log_sink_crn": "crn:v1:bluemix:public:logdna:eu-de:a/3516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
      "name": "my-logdna-log-sink",
      "etag": "\"c3a43545a7f2675970671ac3a57b8db067a1866b2222e1b950ee8da612e347c6\"",
      "type": "logdna",
      "created_at": "2024-06-20T18:30:00.143156Z",
      "updated_at": "2024-06-20T18:30:00.143156Z",
      "parameters": {
        "host": "www.example.com",
        "port": 8080
      }
    },
    {
      "id": "BFB84FFB-6C2D-4204-A354-829F180B1D8B",
      "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:42DAB2C2-BEC2-43E3-8E90-F0259087A884::",
      "name": "my-logs-log-sink",
      "etag": "\"c7e475a63f3e9dcd74e432ead845be0821e839e08b087ad5fafd87907d21dbfd\"",
      "type": "logs",
      "created_at": "2024-06-20T18:30:00.143156Z",
      "updated_at": "2024-06-20T18:30:00.143156Z",
      "parameters": {
        "host": "www.example.com",
        "port": 8080
      }
    }
  ]
}
  • {
  "errors": [
    {
      "code": "incorrect_field",
      "message": "The value for 'name' is not valid. The value must be between 1 and 35 characters in length and can only contain these characters: [a-z,A-Z,0-9,-]",
      "more_info": "https://test.cloud.ibm.com/apidocs/logs-router-service-api#create-tenant",
      "target": {
        "type": "field",
        "name": "service_name"
      }
    }
  ],
  "status_code": 400
}
  • {
  "errors": [
    {
      "code": "failure_getting_authorization_claims",
      "message": "Failed to get authorization claims. Error: token is malformed: token contains an invalid number of segments"
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have authority to create a tenant."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "incorrect_or_missing_header",
      "message": "Missing or incorrect header: 'Content-Type'"
    }
  ],
  "status_code": 415
}

Retrieve a tenant

Retrieve a tenant

GET /tenants/{tenant_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.read

    Mandatory permission to read a tenant ID. It's also part of the role definition named Manager and Reader.

Auditing

Calling this method generates the following auditing event.

When retrieving detail information about a tenant, the following event is generated.

  • logs-router.tenant.read

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Path Parameters

  • tenant_id
    Required*
    string

    The instance ID of the tenant

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

  • curl -X GET "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants/8717DB99-2CFB-4BA6-A033-89C994C2E9F0" --header 'Authorization: Bearer TOKEN' --header 'IBM-API-Version: 2024-06-15'

Response

Response Body

Tenant

Full tenant description

Status Code

  • 200

    Successful operation

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 415

    Wrong Content-Type

  • 500

    Internal server error

Example responses
  • {
  "id": "8717DB99-2CFB-4BA6-A033-89C994C2E9F0",
  "created_at": "2024-06-20T18:30:00.143156Z",
  "updated_at": "2024-06-20T18:30:00.143156Z",
  "crn": "crn:v1:bluemix:public:logs-router:eu-de:a/6516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
  "name": "tenant",
  "etag": "\"822b4b5423e225206c1d75666595714a11925cd0f82b229839864443d6c3c049\"",
  "targets": [
    {
      "id": "C1C1C838-A4AC-4BD7-8BC6-3173B272429D",
      "log_sink_crn": "crn:v1:bluemix:public:logdna:eu-de:a/3516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
      "name": "my-logdna-log-sink",
      "etag": "\"c3a43545a7f2675970671ac3a57b8db067a1866b2222e1b950ee8da612e347c6\"",
      "type": "logdna",
      "created_at": "2024-06-20T18:30:00.143156Z",
      "updated_at": "2024-06-20T18:30:00.143156Z",
      "parameters": {
        "host": "www.example.com",
        "port": 8080
      }
    },
    {
      "id": "BFB84FFB-6C2D-4204-A354-829F180B1D8B",
      "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:42DAB2C2-BEC2-43E3-8E90-F0259087A884::",
      "name": "my-logs-log-sink",
      "etag": "\"c7e475a63f3e9dcd74e432ead845be0821e839e08b087ad5fafd87907d21dbfd\"",
      "type": "logs",
      "created_at": "2024-06-20T18:30:00.143156Z",
      "updated_at": "2024-06-20T18:30:00.143156Z",
      "parameters": {
        "host": "www.example.com",
        "port": 8080
      }
    }
  ]
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "Failed to get authorization claims. Error: token is malformed: token contains an invalid number of segments"
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have authority to read the tenant details."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "tenant_id_not_found",
      "message": "The tenant ID specified (8717DB99-2CFB-4BA6-A033-89C994C2E9F0) was not found in the database."
    }
  ],
  "status_code": 404
}
  • {
  "errors": [
    {
      "code": "incorrect_or_missing_header",
      "message": "Missing or incorrect header: 'Content-Type'"
    }
  ],
  "status_code": 415
}
  • {
  "errors": [
    {
      "code": "failure_getting_tenant",
      "message": "An error occurred while getting account information from the database."
    }
  ],
  "status_code": 500
}

Delete (offboard) a tenant

Delete (offboard) a tenant

DELETE /tenants/{tenant_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.delete

    Mandatory permission to delete (offboard) a tenant. It's also part of the role definition named Manager.

Auditing

Calling this method generates the following auditing event.

When deleting a tenant, the following event is generated.

  • logs-router.tenant.delete

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Path Parameters

  • tenant_id
    Required*
    string

    The instance ID of the tenant

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

  • curl -X DELETE "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants/<your-tenant-id>" --header 'Authorization: Bearer TOKEN' --header 'IBM-API-Version: 2024-06-15'

Response

Status Code

  • 204

    Successfully deleted

  • 400

    Invalid tenant ID

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "errors": [
    {
      "code": "incorrect_parameter",
      "message": "The 'tenantID' specified (8717DB99-2CFB-4BA6-A033) is not valid.",
      "target": {
        "type": "parameter",
        "name": "tenant_id"
      }
    }
  ],
  "status_code": 400
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "Failed to get authorization claims."
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have the authority to delete a tenant."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "tenant_id_not_found",
      "message": "The tenant ID specified (8717DB99-2CFB-4BA6-A033-89C994C2E9F0) was not found in the database."
    }
  ],
  "status_code": 404
}
  • {
  "errors": [
    {
      "code": "failure_deleting_tenant",
      "message": "An error occurred while deleting the tenant from the database.",
      "more_info": "https://test.cloud.ibm.com/apidocs/logs-router-service-api"
    }
  ],
  "status_code": 500
}

Update a tenant

Update a tenant

PATCH /tenants/{tenant_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.update

    Mandatory permission to update a tenant setup. It's also part of the role definition named Manager.

Auditing

Calling this method generates the following auditing event.

When updating the data for a tenant, the following event is generated.

  • logs-router.tenant.update

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • If-Match
    Required*
    string

    ETag provided by GET, POST or PATCH

    Possible values: length = 66, Value must match regular expression (?:W/)?"(?:[ !#-\x7E\x80-\xFF]*| [ ]|\.)*"

Path Parameters

  • tenant_id
    Required*
    string

    The instance ID of the tenant

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

Request Body

Required*
application/merge-patch+jsonTenantPatch

Update of a tenant.

Examples: 
{
  "name": "new-tenant-name"
}
  • curl -X PATCH "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants/8717DB99-2CFB-4BA6-A033-89C994C2E9F0" --header 'Authorization: Bearer TOKEN' --header 'Content-Type: application/merge-patch+json' --header 'IBM-API-Version: 2024-06-15' --header 'If-Match: "8f331e16860324d04ed5c7c90fa076b725a1f440fd19e2885cdc930ff8366f2a"' --data '{"name":"a-new-name"}'

Response

Response Body

Tenant

Full tenant description

Status Code

  • 200

    Successful operation

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 412

    Precondition failed

  • 415

    Wrong Content-Type

  • 500

    Internal server error

Example responses
  • {
  "id": "8717DB99-2CFB-4BA6-A033-89C994C2E9F0",
  "created_at": "2024-06-20T18:30:00.143156Z",
  "updated_at": "2024-06-20T18:30:00.143156Z",
  "crn": "crn:v1:bluemix:public:logs-router:eu-de:a/6516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
  "name": "tenant",
  "etag": "\"822b4b5423e225206c1d75666595714a11925cd0f82b229839864443d6c3c049\"",
  "targets": [
    {
      "id": "C1C1C838-A4AC-4BD7-8BC6-3173B272429D",
      "log_sink_crn": "crn:v1:bluemix:public:logdna:eu-de:a/3516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
      "name": "my-logdna-log-sink",
      "etag": "\"c3a43545a7f2675970671ac3a57b8db067a1866b2222e1b950ee8da612e347c6\"",
      "type": "logdna",
      "created_at": "2024-06-20T18:30:00.143156Z",
      "updated_at": "2024-06-20T18:30:00.143156Z",
      "parameters": {
        "host": "www.example.com",
        "port": 8080
      }
    },
    {
      "id": "BFB84FFB-6C2D-4204-A354-829F180B1D8B",
      "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:42DAB2C2-BEC2-43E3-8E90-F0259087A884::",
      "name": "my-logs-log-sink",
      "etag": "\"c7e475a63f3e9dcd74e432ead845be0821e839e08b087ad5fafd87907d21dbfd\"",
      "type": "logs",
      "created_at": "2024-06-20T18:30:00.143156Z",
      "updated_at": "2024-06-20T18:30:00.143156Z",
      "parameters": {
        "host": "www.example.com",
        "port": 8080
      }
    }
  ]
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "Failed to get authorization claims. Error: token is malformed: token contains an invalid number of segments"
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have authority to read the tenant details."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "tenant_id_not_found",
      "message": "The tenant ID specified (8717DB99-2CFB-4BA6-A033-89C994C2E9F0) was not found in the database."
    }
  ],
  "status_code": 404
}
  • {
  "errors": [
    {
      "code": "precondition_failed",
      "message": "The content of the 'If-Match' header does not match the expectation."
    }
  ],
  "status_code": 415
}
  • {
  "errors": [
    {
      "code": "incorrect_or_missing_header",
      "message": "Missing or incorrect header: 'Content-Type'"
    }
  ],
  "status_code": 415
}
  • {
  "errors": [
    {
      "code": "failure_getting_tenant",
      "message": "An error occurred while getting account information from the database."
    }
  ],
  "status_code": 500
}

List targets for a tenant

List targets for a tenant

GET /tenants/{tenant_id}/targets

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.read

    Mandatory permission to read a tenant ID. It's also part of the role definition named Manager and Reader.

Auditing

Calling this method generates the following auditing event.

When retrieving detail information about a tenant, the following event is generated.

  • logs-router.tenant.read

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Path Parameters

  • tenant_id
    Required*
    string

    The instance ID of the tenant

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

Query Parameters

  • name
    string

    Optional: Name of the tenant target

    Possible values: 1 ≤ length ≤ 35, Value must match regular expression [A-F,0-9,-]

  • curl -X GET "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants/8717DB99-2CFB-4BA6-A033-89C994C2E9F0/targets" --header 'Authorization: Bearer TOKEN' --header 'IBM-API-Version: 2024-06-15'

Response

Response Body

TargetCollection

Response body from a successful list targets operation

Status Code

  • 200

    Successful operation

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 415

    Wrong Content-Type

  • 500

    Internal server error

Example responses
  • {
  "targets": [
    {
      "id": "C1C1C838-A4AC-4BD7-8BC6-3173B272429D",
      "log_sink_crn": "crn:v1:bluemix:public:logdna:eu-de:a/3516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
      "name": "my-logdna-log-sink",
      "etag": "\"c3a43545a7f2675970671ac3a57b8db067a1866b2222e1b950ee8da612e347c6\"",
      "type": "logdna",
      "created_at": "2024-06-20T18:30:00.143156Z",
      "updated_at": "2024-06-20T18:30:00.143156Z",
      "parameters": {
        "host": "www.example.com",
        "port": 8080
      }
    },
    {
      "id": "BFB84FFB-6C2D-4204-A354-829F180B1D8B",
      "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:42DAB2C2-BEC2-43E3-8E90-F0259087A884::",
      "name": "my-logs-log-sink",
      "etag": "\"c7e475a63f3e9dcd74e432ead845be0821e839e08b087ad5fafd87907d21dbfd\"",
      "type": "logs",
      "created_at": "2024-06-20T18:30:00.143156Z",
      "updated_at": "2024-06-20T18:30:00.143156Z",
      "parameters": {
        "host": "www.example.com",
        "port": 8080
      }
    }
  ]
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "Failed to get authorization claims. Error: token is malformed: token contains an invalid number of segments"
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have authority to read the tenant details."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "tenant_id_not_found",
      "message": "The tenant ID specified (8717DB99-2CFB-4BA6-A033-89C994C2E9F0) was not found in the database."
    }
  ],
  "status_code": 404
}
  • {
  "errors": [
    {
      "code": "incorrect_or_missing_header",
      "message": "Missing or incorrect header: 'Content-Type'"
    }
  ],
  "status_code": 415
}
  • {
  "errors": [
    {
      "code": "failure_getting_tenant",
      "message": "An error occurred while getting account information from the database."
    }
  ],
  "status_code": 500
}

Create a target

Create a new target for a tenant.
Note: The tenant must not already have a target of the specified type. Supported target types are logdna (IBM Log Analysis) and logs (IBM Cloud Logs).

POST /tenants/{tenant_id}/targets

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.update

    Mandatory permission to create (onboard) a tenant. It's also part of the role definition named Manager.

Auditing

Calling this method generates the following auditing event.

When creating a target, the following event is generated.

  • logs-router.tenant.update

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Path Parameters

  • tenant_id
    Required*
    string

    The instance ID of the tenant

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

Request Body

Required*

log-sink endpoint and authentication

  • curl -X POST "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants/<your-tenant-id>/targets" --header 'Authorization: Bearer TOKEN' --header 'Content-Type: application/json' --header 'IBM-API-Version: 2024-06-15' --data '{
  "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:42DAB2C2-BEC2-43E3-8E90-F0259087A884::",
  "name": "my-logs-log-sink",
  "parameters": {
    "host": "www.example.com",
    "port": 8080
  }
}'

Response

Response Body

Parameter set describing a particular type of target

Status Code

  • 201

    Successfully created

  • 400

    Bad Request - invalid body

  • 401

    Unauthorized

  • 403

    Forbidden

  • 415

    Wrong Content-Type

  • 500

    Internal server error

Example responses
  • {
  "id": "8717DB99-2CFB-4BA6-A033-89C994C2E9F0",
  "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
  "name": "my-log-sink",
  "etag": "\"c3a43545a7f2675970671ac3a57b8db067a1866b2222e1b950ee8da612e347c6\"",
  "type": "logs",
  "created_at": "2024-06-20T18:30:00.143156Z",
  "updated_at": "2024-06-20T18:30:00.143156Z",
  "parameters": {
    "host": "www.example.com",
    "port": 8080
  }
}
  • {
  "errors": [
    {
      "code": "incorrect_field",
      "message": "The value for 'name' is not valid. The value must be between 0 and 35 characters in length and must be unique in the scope of the tenant.",
      "more_info": "https://test.cloud.ibm.com/apidocs/logs-router-service-api#create-tenant",
      "target": {
        "type": "field",
        "name": "service_name"
      }
    }
  ],
  "status_code": 400
}
  • {
  "errors": [
    {
      "code": "failure_getting_authorization_claims",
      "message": "Failed to get authorization claims. Error: token is malformed: token contains an invalid number of segments"
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have authority to create a tenant."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "incorrect_or_missing_header",
      "message": "Missing or incorrect header: 'Content-Type'"
    }
  ],
  "status_code": 415
}

Retrieve a target

Retrieve a target

GET /tenants/{tenant_id}/targets/{target_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.read

    Mandatory permission to read a tenant ID. It's also part of the role definition named Manager and Reader.

Auditing

Calling this method generates the following auditing event.

When retrieving detail information about a tenants target, the following event is generated.

  • logs-router.tenant.read

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Path Parameters

  • tenant_id
    Required*
    string

    The instance ID of the tenant

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

  • target_id
    Required*
    string

    The instance ID of the tenant target

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

  • curl -X GET "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants/8717DB99-2CFB-4BA6-A033-89C994C2E9F0/targets/C1C1C838-A4AC-4BD7-8BC6-3173B272429D" --header 'Authorization: Bearer TOKEN' --header 'IBM-API-Version: 2024-06-15'

Response

Response Body

Parameter set describing a particular type of target

Status Code

  • 200

    Successful operation

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 415

    Wrong Content-Type

  • 500

    Internal server error

Example responses
  • {
  "id": "8717DB99-2CFB-4BA6-A033-89C994C2E9F0",
  "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
  "name": "my-log-sink",
  "etag": "\"c3a43545a7f2675970671ac3a57b8db067a1866b2222e1b950ee8da612e347c6\"",
  "type": "logs",
  "created_at": "2024-06-20T18:30:00.143156Z",
  "updated_at": "2024-06-20T18:30:00.143156Z",
  "parameters": {
    "host": "www.example.com",
    "port": 8080
  }
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "Failed to get authorization claims. Error: token is malformed: token contains an invalid number of segments"
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have authority to read the tenant details."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "tenant_id_not_found",
      "message": "The target ID specified (8717DB99-2CFB-4BA6-A033-89C994C2E9F0) was not found in the database."
    }
  ],
  "status_code": 404
}
  • {
  "errors": [
    {
      "code": "incorrect_or_missing_header",
      "message": "Missing or incorrect header: 'Content-Type'"
    }
  ],
  "status_code": 415
}
  • {
  "errors": [
    {
      "code": "failure_getting_tenant",
      "message": "An error occurred while getting account information from the database."
    }
  ],
  "status_code": 500
}

Update a target

Update a target.
Note:A change of the target type is only supported for tenants with a single target.

PATCH /tenants/{tenant_id}/targets/{target_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.update

    Mandatory permission to update a tenant setup. It's also part of the role definition named Manager.

Auditing

Calling this method generates the following auditing event.

When updating the data for a tenant, the following event is generated.

  • logs-router.tenant.update

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • If-Match
    Required*
    string

    ETag provided by GET, POST or PATCH

    Possible values: length = 66, Value must match regular expression (?:W/)?"(?:[ !#-\x7E\x80-\xFF]*| [ ]|\.)*"

Path Parameters

  • tenant_id
    Required*
    string

    The instance ID of the tenant

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

  • target_id
    Required*
    string

    The instance ID of the tenant target

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

Request Body

Required*
application/merge-patch+jsonTargetPatch

Updates a target of a tenant.

  • curl -X PATCH "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants/8717DB99-2CFB-4BA6-A033-89C994C2E9F0/targets/C1C1C838-A4AC-4BD7-8BC6-3173B272429D" --header 'Authorization: Bearer TOKEN' --header 'Content-Type: application/merge-patch+json' --header 'IBM-API-Version: 2024-06-15' --header 'If-Match: "8f331e16860324d04ed5c7c90fa076b725a1f440fd19e2885cdc930ff8366f2a"' --data '{ 
   "log_sink_crn": "crn:v1:bluemix:public:logdna:eu-de:a/3516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::", 
   "name": "my-log-sink", 
   "parameters": { 
      "host": "www.example.com", 
      "port": 8080, 
      "access_credential": "an-ingestion-secret" 
   } 
}'

Response

Response Body

Parameter set describing a particular type of target

Status Code

  • 200

    Successful operation

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 412

    Precondition failed

  • 415

    Wrong Content-Type

  • 500

    Internal server error

Example responses
  • {
  "id": "8717DB99-2CFB-4BA6-A033-89C994C2E9F0",
  "log_sink_crn": "crn:v1:bluemix:public:logs:eu-de:a/4516b8fa0a174a71899f5affa4f18d78:3517d2ed-9429-af34-ad52-34278391cbc8::",
  "name": "my-log-sink",
  "etag": "\"c3a43545a7f2675970671ac3a57b8db067a1866b2222e1b950ee8da612e347c6\"",
  "type": "logs",
  "created_at": "2024-06-20T18:30:00.143156Z",
  "updated_at": "2024-06-20T18:30:00.143156Z",
  "parameters": {
    "host": "www.example.com",
    "port": 8080
  }
}
  • {
  "errors": [
    {
      "code": "update_failed",
      "message": "Target type cannot be changed. Only one target of each type is allowed"
    }
  ],
  "status_code": 400
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "Failed to get authorization claims. Error: token is malformed: token contains an invalid number of segments"
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have authority to read the tenant details."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "tenant_id_not_found",
      "message": "The tenant ID specified (8717DB99-2CFB-4BA6-A033-89C994C2E9F0) was not found in the database."
    }
  ],
  "status_code": 404
}
  • {
  "errors": [
    {
      "code": "precondition_failed",
      "message": "The content of the 'If-Match' header does not match the expectation."
    }
  ],
  "status_code": 415
}
  • {
  "errors": [
    {
      "code": "incorrect_or_missing_header",
      "message": "Missing or incorrect header: 'Content-Type'"
    }
  ],
  "status_code": 415
}
  • {
  "errors": [
    {
      "code": "failure_getting_tenant",
      "message": "An error occurred while getting account information from the database."
    }
  ],
  "status_code": 500
}

Delete a target

Delete a target.
Note: The last target is not allowed to be deleted.

DELETE /tenants/{tenant_id}/targets/{target_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • logs-router.tenant.update

    Mandatory permission to update a tenant. It's also part of the role definition named Manager.

Auditing

Calling this method generates the following auditing event.

When deleting a target, the following event is generated.

  • logs-router.tenant.update

Request

Custom Headers

  • IBM-API-Version
    Required*
    string

    Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date can be provided. Specify the current date to request the latest version.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Path Parameters

  • tenant_id
    Required*
    string

    The instance ID of the tenant

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

  • target_id
    Required*
    string

    The instance ID of the tenant target

    Possible values: length = 36, Value must match regular expression [A-F,0-9,-]

  • curl -X DELETE "https://management.private.{region}.logs-router.cloud.ibm.com/v1/tenants/<your-tenant-id>/targets/<your-target-id>" --header 'Authorization: Bearer TOKEN' --header 'IBM-API-Version: 2024-06-15'

Response

Status Code

  • 204

    Successfully deleted

  • 400

    Invalid tenant ID

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "errors": [
    {
      "code": "incorrect_parameter",
      "message": "The 'tenantID' specified (8717DB99-2CFB-4BA6-A033) is not valid.",
      "target": {
        "type": "parameter",
        "name": "tenant_id"
      }
    }
  ],
  "status_code": 400
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "Failed to get authorization claims."
    }
  ],
  "status_code": 401
}
  • {
  "errors": [
    {
      "code": "not_authorized",
      "message": "The specified token does not have the authority to delete a tenant."
    }
  ],
  "status_code": 403
}
  • {
  "errors": [
    {
      "code": "tenant_id_not_found",
      "message": "The tenant ID specified (8717DB99-2CFB-4BA6-A033-89C994C2E9F0) was not found in the database."
    }
  ],
  "status_code": 404
}
  • {
  "errors": [
    {
      "code": "failure_deleting_tenant",
      "message": "An error occurred while deleting the tenant from the database.",
      "more_info": "https://test.cloud.ibm.com/apidocs/logs-router-service-api"
    }
  ],
  "status_code": 500
}
id=curlclassName=tab-item-selected