> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md).

# Identity and ISP Routing

The agent reports identity values when it registers. ThousandEyes uses the agreed routing configuration to decide where the agent appears.

| Value    | Purpose                                                                                                           |
| -------- | ----------------------------------------------------------------------------------------------------------------- |
| `client` | Identifies the ISP, customer, or OEM route.                                                                       |
| `base`   | Identifies the device model or SKU. It is used for routing only when a rule must be limited to selected models.   |
| `secret` | Authorizes the agent to register. It is not an account-group mapping field.                                       |
| ASN      | Identifies the network from the agent's public IP. ThousandEyes can use it when firmware cannot identify the ISP. |

## First Registration

When an agent first registers, it receives a Unit ID and is assigned to an organization and account group.

Changing `base`, `client`, or the MAC in `skagent.cfg` does not update those values for an agent that is already registered. Confirm the production values before the corresponding field trial or rollout. Contact ThousandEyes to correct an existing registration.

## Choosing the Identity Pattern

Decide how the production firmware will identify the ISP during integration design. Confirm the exact values after the first working build.

| Scenario                                               | Production `client`                               |
| ------------------------------------------------------ | ------------------------------------------------- |
| One known ISP or customer                              | The organization's `client` string.               |
| Shared multi-ISP firmware that can identify the ISP    | A label read from the firmware or a platform API. |
| Shared multi-ISP firmware that cannot identify the ISP | A stable label chosen by the OEM.                 |

## Lab Identity

During integration development, use the lab identity configuration so the agent appears in the organization conducting the lab integration.

Use the Org Client ID and lab authentication secret supplied by ThousandEyes:

```toml
[identity]
base='examplemodel'
client='CHANGE ME'

[authentication]
secret='CHANGE ME'
```

Replace `base` with the model being tested. Replace the two `CHANGE ME` values with the lab Org Client ID and lab secret. Do not include the lab secret in production firmware.

## Production Identity

Do not use the lab authentication secret in production.

Inject the production secret through the target's provisioning or secret-management process. Do not embed it in a distributable firmware image.

### 1. Firmware Identifies the ISP

Use a stable value that the firmware already knows. The value can come from a file, program, RDK-B data model, OpenSync API, or another platform source.

Use a value the firmware already has to identify the ISP. For example, read it from a provisioning file:

```toml
[identity]
base='examplemodel'

[identity.client]
input='file'
path='/etc/device/isp'

[authentication]
secret='CHANGE ME'
```

Confirm the value returned on the target with ThousandEyes before the corresponding ISP field trial. Inject the production authentication secret during provisioning or at first boot.

### 2. Firmware Cannot Identify the ISP

Use a stable OEM `client` for generic firmware.

Use a stable OEM label when generic firmware cannot identify the ISP:

```toml
[identity]
base='examplemodel'
client='example-oem-retail'

[authentication]
secret='CHANGE ME'
```

Replace the example values with the agreed model and OEM `client`. Inject the production authentication secret during provisioning or at first boot.

## How ThousandEyes Determines Routing

After the integration works, provide ThousandEyes with the following information:

1. If using a label for the `client` instead of a ThousandEyes provisioned client string, give ThousandEyes the observed `client` and whether it is fixed or dynamic.
2. Give the reported `base` only when routing may need to be restricted by model.

ThousandEyes then selects the broadest mapping that identifies the intended devices without capturing another agent population:

| Situation                                                                                                      | Preferred mapping     |
| -------------------------------------------------------------------------------------------------------------- | --------------------- |
| A stable `client` uniquely identifies the ISP across models                                                    | `client`              |
| Shared generic firmware cannot identify the ISP, and every relevant agent on the ISP's ASN belongs to that ISP | `ASN`                 |
| Shared generic firmware cannot identify the ISP, but only selected models on the ASN should be included        | `ASN + base`          |
| A reused `client` should apply only to selected models                                                         | `client + base`       |
| A broad OEM `client` needs a model- and ISP-specific override                                                  | `client + base + ASN` |

The ISP and OEM do not configure these mappings themselves.

### Routing Examples

**Firmware Identifies the ISP**

Acme, an OEM and device vendor, builds one firmware image for several ISPs. The firmware reads the ISP from its provisioning data and reports `examplenet` as the agent's `client` value.

Once the integration is running, Acme confirms the exact value with ThousandEyes. Because ExampleNet is already a ThousandEyes customer, ThousandEyes maps `examplenet` to ExampleNet's account group.

The `client` value identifies the ISP across every supported Acme model. Acme OEM and ExampleNet validate the mapping by activating a small number of devices and confirming that those devices appear in ExampleNet's account.

**Generic Firmware Cannot Identify the ISP**

Acme, an OEM and device vendor, ships generic retail firmware that cannot identify the ISP. Every device therefore reports `acme-retail` as its `client` value. Devices without an ISP-specific mapping register with an internal ThousandEyes organization. You can migrate them to the appropriate organization later.

ExampleNet later plans to deploy the agent on Acme AX500 devices. Because the firmware still reports `acme-retail`, ThousandEyes confirms ExampleNet's ASN.

If every relevant agent on that ASN should belong to ExampleNet, ThousandEyes can use an ASN mapping. If the mapping must apply only to AX500 devices, ThousandEyes adds the reported `base` value.

Acme validates the integration on representative hardware. ExampleNet then confirms that the field-trial devices appear in its account and report expected results.

## Confirming the Resolved Values

On the target, verify that production values are present, correct, and stable after reboot. Correct missing or incorrect values, or choose a source that remains stable.

Use the [Configuration Reference](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/configuration-reference.md) for field details and input types, and the applicable [Generic Linux](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/generic-linux.md), [OpenWrt](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/openwrt.md), [RDK-B](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/rdk-b.md), or [OpenSync](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/opensync.md) guide for commands.

Confirm the resolved production `client` with ThousandEyes before the corresponding ISP field trial or production deployment.
