---
title: "UA Deployment"
slug: "ua-deployment"
description: "Deploy Universal Agents securely with provisioning tokens via the portal or API, ensuring streamlined onboarding and robust security for your organization."
status: "new"
updated: 2026-10-01T23:12:06Z
published: 2026-10-01T23:12:06Z
canonical: "kb.kentik.com/ua-deployment"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://kb.kentik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UA Deployment

You can deploy a Universal Agent through the portal or programmatically through the API. Choose [**portal deployment**](/v1/docs/ua-deployment#deploy-a-universal-agent-through-the-portal) for a guided setup of smaller deployments, or [**API deployment**](/v1/docs/ua-deployment#deploy-a-universal-agent-through-the-kentik-api) when automating programmatic or partner-driven fleet rollouts at scale.

All Universal Agent deployments require a **provisioning token**.

## About Provisioning Tokens

A provisioning token securely registers Universal Agents over the Kentik API without requiring manual portal access or long-lived credentials. Upon initial startup, the agent reads the token from the `K_REGISTER_PROVISIONING_TOKEN` environment variable to register itself directly. You can configure tokens to auto-approve agents immediately or hold them in a `Not Authorized` status until an administrator grants approval. This mechanism provides a low-risk, fully scriptable onboarding workflow across standalone Linux hosts, Docker containers, and Kubernetes clusters.

Provisioning tokens enforce the following security and multi-tenant rules:

- **Organization Scope:** Kentik strictly binds each token to a single organization, preventing you from transferring an agent to another organization post-registration.
- **Short Lifespan & Usage Caps:** Custom expiration schedules and strict usage caps (`maxUsageCount`) eliminate long-lived credential risks.
- **Runtime Token Updates:** The `K_REGISTER_PROVISIONING_TOKEN` environment variable overrides install-time credentials, allowing you to replace expired tokens without reinstalling the agent binary.
- **Partner & Third-Party Onboarding:** Partner teams and system integrators can deploy agents into a customer organization safely over the API without requiring portal login access or persistent credentials.
- **Clean Staging & Org Locking:** Because registered agent identities are permanently tied to the issuing organization, staging agents in a lab organization requires re-registering them with a customer-scoped token before customer deployment.

## Token Authorization Statuses

The following table describes token authorization statuses for portal and API deployments.

| Token Type | Behavior | Portal Deployment | API Deployment |
| --- | --- | --- | --- |
| **Auto-Approve Tokens** | Agents automatically register and transition directly to **Up** status. | Deployed automatically. | Use the flag `requiresApproval: false`. |
| **Approval-Required Tokens** | Agents register in **Not Authorized** status until approved. | Admin must click **Authorize** in the portal. | Use the flag `requiresApproval: true`. |

## Token Revocation & Risk Management

To maintain a minimal exposure window, set a strict `maxUsageCount` and short expiry when creating a provisioning token. Once all intended agents in a deployment run have registered, you can immediately revoke the token via the `kagent` provisioning-tokens API. Revoking a provisioning token prevents new agents from registering with those credentials while leaving already registered and authorized agents unaffected.

## Deploy a Universal Agent Through the Portal

To deploy a new instance of the Universal Agent via Docker or Linux through the portal, follow these steps:

1. Navigate to the [**Universal Agents**](/v1/docs/ua-ui-reference) page via **Settings** **»** **Universal Agents** in the Kentik portal’s main nav menu.
2. Click **+ Deploy Agent** to open the dialog.
3. Under **Installation**, select Docker or Linux and click the corresponding tab. The generated command that appears automatically bundles your company ID (`K_COMPANY_ID`) and a provisioning token (`K_REGISTER_PROVISIONING_TOKEN`).
4. Click **Copy** to copy the command from the text area.
5. Open a terminal window on the host machine and paste the command. (To use a web proxy, see [**Install Agent via Web Proxy**](/v1/docs/ua-deployment#install-agent-via-web-proxy)).
6. Run the command. The new agent will appear in the **Select an Agent** list. The **Host Name** column will vary as follows:
  1. **Docker**: The agent's Docker container ID.
  2. **Linux**: The hostname of the Linux system where the agent was installed.
7. Click **Authorize** to authorize the agent to connect with Kentik. The dialog will refresh with basic information, optional fields, and a **Continue** button.

![](https://cdn.us.document360.io/082e25b5-afce-42d4-8f47-70bd3f1d02b7/Images/Documentation/image(649).png)
8. Optionally add **Display Name**, **Description,** and **Site Name**. Click **Continue** to proceed.
9. Select the capabilities to enable for this agent by clicking the toggle switch next to each capability.

![Deployment options for the Universal Agent, highlighting SNMP and Syslog capabilities.](https://cdn.us.document360.io/082e25b5-afce-42d4-8f47-70bd3f1d02b7/Images/Documentation/UA-deploy-agent-dialog-capability-selection(1).png)
10. Click the **Finish** button to complete the deployment process. Once deployed, the agent will appear on the [**Universal Agents List**](/v1/docs/ua-ui-reference#universal-agents-list).

> [!TIP]
> **Tip:** If you close the dialog before clicking Authorize, the agent will appear on the [**Universal Agents List**](/v1/docs/ua-ui-reference#universal-agents-list) with a “Not Authorized“ status and won't be functional. To resolve this, click **Deploy Agent** to reopen the dialog and click **Authorize**.

> [!NOTE]
> **Note:** A token generated through a portal installation has a time-to-live (TTL) of one hour. You can register as many agents as you wish during that one-hour window before requesting a new token. After this timeframe, you will need to re-run the generated command in Step 3 to generate a new provisioning token and continue installations.

### Install Agent via Web Proxy

Use the `https_proxy` environment variable to set the proxy's URL:

- **Docker**: Provide the environment variable as part of the `docker run` command:

`--env https_proxy=http://address.of.your.proxy`
- **Linux**: Set the environment variable before running the install command:

`export https_proxy=http://address.of.your.proxy`

## Deploy a Universal Agent Through the Kentik API

For portal-free automated universal agent deployments across hosts, Docker, or Kubernetes clusters, follow these steps:

> [!NOTE]
> **Notes:**
> 
> - Before starting, ensure you have the following:
>   - A Kentik API user (email + API token) for the target organization.
>   - The target organization's company ID.
>   - Network Egress to `grpc.api.kentik.com` (US) or `grpc.api.kentik.eu` (EU) on port `443`.

1. Create a **provisioning token** in the target organization by executing a `POST` request against the API host for the target organization's region. The account you authenticate with determines which organization the token belongs to.

```bash
curl -sS -X POST \
  -H "Content-Type: application/json" \
  -H "X-CH-Auth-Email: $K_API_EMAIL" \
  -H "X-CH-Auth-API-Token: $K_API_TOKEN" \
  -d '{
    "name": "poc-fleet",
    "maxUsageCount": 5,
    "requiresApproval": false,
    "config": { "siteId": "1234" }
  }' \
  https://grpc.api.kentik.com/kagent/v202401/provisioning-tokens
```

> [!TIP]
> **Tip:** You can customize the token's expiration schedule when creating it via the [Provisioning Tokens API](https://github.com/kentik/api-schema-public/blob/master/gen/openapiv3/kentik/kagent/v202401/provisioning_token.swagger.json) by passing a future ISO 8601 timestamp in the `expiresAt` payload attribute, for example:
> 
> 
> 
> ```json
> "expiresAt": "2026-07-04T12:18:53.092Z"
> ```
> 
> 
> 
> See the [Provisioning Tokens API reference](https://github.com/kentik/api-schema-public/blob/master/gen/openapiv3/kentik/kagent/v202401/provisioning_token.swagger.json) for full schema details.
2. Extract the token value by locating the generated token string within the JSON response under `.token.token`. This value is the secure credential that must be handed to the deploying agents.
3. Deploy the agents with the token.
  1. **Standalone Linux or Docker:** Supply the token directly to the host's bootstrap environment before launching the agent service:

```bash
export K_COMPANY_ID=<target-company-id>
export K_REGISTER_PROVISIONING_TOKEN=<token-value>
```

> [!NOTE]
> **Note:** The `K_REGISTER_PROVISIONING_TOKEN` variable overrides any values stored at install time, allowing you to update expired tokens without reinstalling the agent.
  2. **Kubernetes (Helm):** Pass the company ID and token as strings into the chart parameters during installation:

```bash
helm install kagent https://github.com/kentik/kagent-helm/archive/refs/heads/main.tar.gz \
  --set-string kagent.companyId=<target-company-id> \
  --set-string kagent.provisioningToken=<token-value>
```

> [!NOTE]
> **Notes:**
> 
> - Set `maxUsageCount` on the token to at least the number of replicas you deploy, as each individual pod will consume one use.
> - If you are using the Kubernetes Helper, you can also use the [generate-provisioning-token.sh](https://github.com/kentik/kagent-helm/blob/main/generate-provisioning-token.sh) helper script included in the kagent-helm repository to automate token creation.
> - [Deploy Universal Agents with Helm](/v1/docs/deploy-agents-with-helm) provides more information for deploying Universal Agents with Helm.
4. Retrieve the agent's install ID by querying the API to list all agents awaiting authorization within the target organization to capture your specific `install.id`:

```bash
# List agents awaiting authorization to get the install ID
curl -sS -H "X-CH-Auth-Email: $K_API_EMAIL" -H "X-CH-Auth-API-Token: $K_API_TOKEN" \
  "https://grpc.api.kentik.com/kagent/v202401/agents?unregistered=true" \
  | jq -r '.agents[] | "\(.install.id)\t\(.install.hostMetadata.hostname)"'
```
5. Authorize the agent by submitting a `PUT` request containing the retrieved `install-id` to complete the secure verification process. The API response returns a permanent, numeric `agent-id`.

```bash
curl -sS -H "X-CH-Auth-Email: $K_API_EMAIL" -H "X-CH-Auth-API-Token: $K_API_TOKEN" -X PUT \
  "https://grpc.api.kentik.com/kagent/v202401/agents/authorize/<install-id>"
```
6. Enable and configure agent capabilities programmatically. Once the agent status shows as **Up**, enable specific capability names via PATCH request using the returned `agent-id`name:

```bash
curl -sS -H "X-CH-Auth-Email: $K_API_EMAIL" -H "X-CH-Auth-API-Token: $K_API_TOKEN" \
  -X PATCH -H "Content-Type: application/json" \
  -d '{"enabled":true}' \
  "https://grpc.api.kentik.com/kagent/v202401/agents/<agent-id>/capabilities/kproxy"
```

> [!TIP]
> **Tip:** If you deploy an agent using an auto-approve token (`requiresApproval: false`), the agent is automatically authorized upon initial registration. You can skip the step to **Authorize the agent** and proceed directly to managing capabilities.