---
name: logs-router-tenant-create
title: Creating a tenant and a target destination
description: To manage platform logs that are generated by IBM Cloud® services in a region of IBM Cloud, you must create a tenant in each region that you operate.
last-updated: 2025-07-03
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/logs-router?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Creating a tenant and a target destination
{: #tenant-create}

To manage platform logs that are generated by IBM Cloud® services in a region of IBM Cloud, you must create a tenant in each region that you operate.
{: shortdesc}

A tenant is the account-specific configuration of IBM Cloud Logs Routing running within a region. You can define up to 1 target destination per tenant per region. The target defines where the logs are routed.

The create request requires that you create a target destination when you create the tenant in a region.
{: important}


## Before you begin
{: #tenant-create-prereqs}

Complete the following steps:

- Review [About IBM® Cloud Logs Routing](https://cloud.ibm.com/docs/logs-router?topic=logs-router-about&format=markdown) to understand concepts.

- Install all prerequisite tools as described in the [getting started](https://cloud.ibm.com/docs/logs-router?topic=logs-router-getting-started&interface=ui&format=markdown#getting-started-before-you-begin).

- Set up permissions to manage targets in the account. For more information, see [Setting up IAM permissions for managing tenants](https://cloud.ibm.com/docs/logs-router?topic=logs-router-iam&interface=ui&format=markdown).

- To get details on a tenant by using the API, check that you can connect to IBM Cloud Logs Routing by using the management API. For more information, see [Connecting to IBM® Cloud Logs Routing](https://cloud.ibm.com/docs/logs-router?topic=logs-router-about&format=markdown#about_connecting).

## Retrieving the IAM bearer token
{: #tenant-create-retrieve-iam-token-cli}
{: api}

You must get an IBM Cloud® Identity and Access Management (IAM) access token to authenticate your requests to the IBM® Cloud Logs Routing service. For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/logs-router?topic=logs-router-retrieve-access-token&format=markdown).

For example, you can retrieve your IAM bearer token and export it as an environment variable by running the following CLI command:

```sh
export IAM_TOKEN=`ibmcloud iam oauth-tokens --output json | jq -r '.iam_token'`
```
{: pre}



## Choosing the management endpoint
{: #tenant-create-endpoint}
{: api}


A tenant is the account-specific configuration of IBM Cloud Logs Routing running within a region.

To get the details of a tenant in a region, you must use the management endpoint URL for the region where the tenant is configured.
{: important}

You can use private or public endpoints.

For more information, see [Management endpoint URLs](https://cloud.ibm.com/docs/logs-router?topic=logs-router-endpoints&format=markdown).

## Creating a tenant and target through the UI
{: #tenant-create-ui}
{: ui}


When the IBM Cloud Logs Routing console is first displayed, any existing target information is displayed.

If no target is configured for a region, the region displays the **Set target** option. When the target is set for the first time, an IBM Cloud Logs Routing tenant is [created (onboarded)](https://cloud.ibm.com/docs/logs-router?topic=logs-router-about&interface=ui&format=markdown#about_tenants) and the target configured.

To create a tenant and a target for a region, complete the following steps:

1. [Log in to your IBM Cloud account](https://cloud.ibm.com/login){: external}.

2. Click the **Menu** icon ![Menu icon](../icons/icon_hamburger.svg "Menu") > **Observability**.

3. Click **Logging** > **Routing**.

4. Click **Set target**.

5. Select an IBM Cloud Logs instance. This is the instance where you want to receive logs that are routed by IBM Cloud Logs Routing.

   

   You can select an IBM Cloud Logs instance from the list. Before you do, check that you have a service to service authorization defined between the IBM Cloud Logs Routing service and the IBM Cloud Logs instance. For more information, see [Creating a S2S authorization to grant access to send logs to IBM Cloud Logs](https://cloud.ibm.com/docs/logs-router?topic=logs-router-iam-service-auth-logs-routing&format=markdown).

6. Click **Save**.


When you set a target in the UI, you create a tenant in that region. The name of the tenant is set as `region-ID` where region is set to the region where you are located when you create the target.
{: note}

## Creating a tenant and target by using the API
{: #tenant-create-api}
{: api}


Run the following command to create a tenant for the IBM Cloud Logs Routing service by using the **private endpoint**:

```sh
curl -X POST  https://management.private.${REGION}.logs-router.cloud.ibm.com/v1/tenants \
-H "Content-Type: application/json" \
-H "Authorization: ${IAM_TOKEN}" \
-H "IBM-API-Version: API_VERSION_DATE" \
--data '{TARGET_DATA}'
```
{: pre}

Run the following command to create a tenant for the IBM Cloud Logs Routing service by using the **public endpoint**:

```sh
curl -X POST  https://management.${REGION}.logs-router.cloud.ibm.com/v1/tenants \
--H "Content-Type: application/json" \
-H "Authorization: ${IAM_TOKEN}" \
-H "IBM-API-Version: API_VERSION_DATE" \
--data '{TARGET_DATA}'
```
{: pre}

Where
- `REGION` defines the location where the tenant is configured.
- `IAM_TOKEN` defines the credentials that you use to authenticate your requests.
- `API_VERSION_DATE` defines the date of the API version that you want to use to query your tenant definition. The format must be as follows: `YYYY-MM-DD`
- `TARGET_DATA` defines the information about the target destination.

### IBM Cloud Logs destination
{: #tenant-create-api-logs}
{: api}

For a target that defines an IBM Cloud Logs destination, the `TARGET_DATA` format is as follows:

``` text
{
    "name": "TENANT_NAME",
    "targets": [
        {
            "log_sink_crn": "CLOUD_LOGS_INSTANCE_CRN",
            "name": "TARGET_NAME",
            "parameters": {
                "host": "CLOUD_LOGS_INSTANCE_INGRESS_ENDPOINT",
                "port": CLOUD_LOGS_INSTANCE_TARGET_PORT
            }
        }
    ]
}
```
{: codeblock}

Where

- `TENANT_NAME`: Name of the tenant. The name must be unique across tenants for this account and can be up to 35 characters long. The value can only contain these characters: `a-z,0-9,-./`
- `TARGET_NAME`: Name of the target destination. The name must be unique across all targets in the region and can be up to 35 characters long. The value can only contain these characters: `a-z,0-9,-./`
- `CLOUD_LOGS_INSTANCE_CRN` is the CRN of the IBM Cloud Logs instance.
- `CLOUD_LOGS_INSTANCE_INGRESS_ENDPOINT` is the full qualified ingress endpoint for the destination of logs.
- `CLOUD_LOGS_INSTANCE_TARGET_PORT` defines the port to use. For example, `443`.



## Creating a tenant and target by using Terraform
{: #tenant-create-tf}
{: terraform}

### IBM Cloud Logs destination
{: #tenant-create-tf-logs}
{: terraform}


To create tenant with a target of type `logs`, use the following:

```text
provider "ibm" {
  ibmcloud_api_key = "IBMCLOUD_API_KEY"
  region = "some-region"
}

resource "ibm_logs_router_tenant" "logs_router_tenant_instance_1" {
	name = "TENANT_NAME"
  region = "TENANT_REGION"
	targets {
	  log_sink_crn = "CLOUD_LOGS_INSTANCE_CRN"
	  name = "TARGET_NAME"
	  parameters {
		host = "CLOUD_LOGS_INSTANCE_INGRESS_ENDPOINT"
		port = CLOUD_LOGS_INSTANCE_TARGET_PORT
	  }
	}
  }
```
{: codeblock}

Where

- `TENANT_NAME`: Name of the tenant. The name must be unique across tenants for this account and can be up to 35 characters long. The value can only contain these characters: `a-z,0-9,-./`
- `TENANT_REGION`: Region to create the tenant. The value must be in the format of a two-letter code for the region followed by a dash and the three-letter code for the zone (for example, `us-south`). For a list of regions, see [Locations](https://cloud.ibm.com/docs/logs-router?topic=logs-router-locations&format=markdown).
- `TARGET_NAME`: Name of the target destination. The name must be unique across all targets in the region and can be up to 35 characters long. The value can only contain these characters: `a-z,0-9,-./`
- `CLOUD_LOGS_INSTANCE_CRN`: The CRN of the IBM Cloud Logs instance.
- `CLOUD_LOGS_INSTANCE_INGRESS_ENDPOINT`: The full qualified ingress endpoint for the destination of logs.
- `CLOUD_LOGS_INSTANCE_TARGET_PORT`: Defines the port to use. For example, `443`.
- `IBMCLOUD_API_KEY`: This is used to obtain an IAM token to create the tenant. The tenant will be created for the account that issued this API key.