Private Links API

Overview

Use the Private Links API to manage Private Links from your own backend: create a link to a private service in your AWS or Azure network, list the links in a project, check the health of a link, and delete a link.

This API is available through the following clients:

• Go cloudagents client 
• LiveKit CLI 

The Go SDK is the only server SDK that supports this API. To learn how to use it, see Monitor and manage Private Links.

Implementation details

To implement your own client, use the details in the following sections.

Endpoints

The Private Links API is built with Twirp . Arguments are passed as JSON to an endpoint using the POST method.

The Private Links API is accessible via /twirp/livekit.CloudAgent/<MethodName> on the agents.livekit.cloud host, not your project URL. For example:

https://agents.livekit.cloud/twirp/livekit.CloudAgent/ListPrivateLinks

Authorization header

All endpoints require a signed access token with the agent admin grant. The token identifies your project, so each request only reads or changes the Private Links in that project. Set the token using the HTTP header:

Authorization: Bearer <token>

The Go SDK sets this header automatically.

To call the API directly, generate the token in a trusted backend or monitoring job. Never send your API secret as the bearer token or expose it in client-side code.

The lk token create command can't add the agent admin grant, but any JSON Web Token (JWT) library can generate the token. Sign the token with your API secret using the HS256 algorithm, and include the following claims:

For example, the following generates a token that expires after five minutes with the Go SDK:

package main

import (
	"fmt"
	"os"
	"time"

	"github.com/livekit/protocol/auth"
)

func main() {
	token, err := auth.NewAccessToken(os.Getenv("LIVEKIT_API_KEY"), os.Getenv("LIVEKIT_API_SECRET")).
		SetAgentGrant(&auth.AgentGrant{Admin: true}).
		SetValidFor(5 * time.Minute).
		ToJWT()
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(token)
}

The curl examples on this page read the token from the TOKEN environment variable. Save the token you generate to that variable:

export TOKEN="<token>"

Version header

The Private Links API also requires an X-LIVEKIT-CLI-VERSION header. The server reads its value as a semantic version and checks it against a minimum version. Requests without the header, or with an older version, fail with a malformed error. The LiveKit CLI and the Go cloudagents client set this header automatically: the CLI sends its own version, and the Go client sends the Go SDK version.

X-LIVEKIT-CLI-VERSION: <LIVEKIT_CLI_VERSION>

When you call the API directly, send your installed LiveKit CLI version instead of writing a fixed value, so the value doesn't fall below the minimum:

export LIVEKIT_CLI_VERSION="$(lk --version | awk '{print $3}')"

Post body

Twirp expects an HTTP POST request. The body must be a JSON object with the application/json media type, containing parameters specific to that request.

For example, the following lists the Private Links in a project. The ListPrivateLinks method takes no parameters, so the body is an empty object:

curl -X POST https://agents.livekit.cloud/twirp/livekit.CloudAgent/ListPrivateLinks \
	-H "Authorization: Bearer $TOKEN" \
	-H "X-LIVEKIT-CLI-VERSION: $LIVEKIT_CLI_VERSION" \
	-H 'Content-Type: application/json' \
	-d '{}'

The response lists each link in the project:

{
  "items": [
    {
      "private_link_id": "CAPL_a1b2c3d4e5f6",
      "name": "customer-redis",
      "region": "us-east",
      "port": 6379,
      "endpoint": "com.amazonaws.vpce.us-east-1.vpce-svc-0a1b2c3d4e5f67890",
      "connection_endpoint": "customer-redis-p-a1b2c3d4-x1y2z.link",
      "cloud_region": "us-east-1"
    }
  ]
}

When passing in parameters, the server accepts either snake_case or camelCase for keys. Responses use snake_case keys.

API methods

The Private Links API allows you to create, delete, and list Private Links, and to check the status of a link.

CreatePrivateLink

Create a private link to a private service in your AWS or Azure network. Requires the agent admin permission.

After you create a link, approve its connection request in your cloud account. To learn more, see the setup guide for AWS or Azure.

Each project supports a limited number of Private Links in each LiveKit region. To learn more, see Limitations. If the project has reached its limit, the request fails with a resource_exhausted error. If a link with the same name already exists in the project, the request fails with an already_exists error.

Returns CreatePrivateLinkResponse.

DestroyPrivateLink

Delete a private link. Requires the agent admin permission.

After you delete a link, agents can no longer connect through it. If no link with the given ID exists in the project, the request fails with a not_found error. If the link was already deleted, the request succeeds without making any changes.

Returns an empty object.

ListPrivateLinks

List the Private Links in a project. Requires the agent admin permission.

The response doesn't include deleted links or the status of each link. To get the status of a link, use GetPrivateLinkStatus.

Returns ListPrivateLinksResponse.

GetPrivateLinkStatus

Get the current status of a private link. Requires the agent admin permission.

If the link doesn't exist in the project, the request fails with a not_found error.

Returns GetPrivateLinkStatusResponse.

For example, the following request gets the status of a link:

curl -X POST https://agents.livekit.cloud/twirp/livekit.CloudAgent/GetPrivateLinkStatus \
	-H "Authorization: Bearer $TOKEN" \
	-H "X-LIVEKIT-CLI-VERSION: $LIVEKIT_CLI_VERSION" \
	-H 'Content-Type: application/json' \
	-d '{ "private_link_id": "CAPL_a1b2c3d4e5f6" }'

The response contains the status, the time it was last updated, and the reason for it:

{
  "value": {
    "status": "PRIVATE_LINK_STATUS_HEALTHY",
    "updated_at": "2026-09-23T23:41:23.841487Z",
    "reason": ""
  }
}

Types

The Private Links API includes the following types.

PrivateLink

Represents a single private link.

PrivateLinkStatus

The current status of a private link.

Status

The status of a private link. To learn what each status means and how a link moves between them, see Status values.

CreatePrivateLinkResponse

Returned by CreatePrivateLink.

ListPrivateLinksResponse

Returned by ListPrivateLinks.

GetPrivateLinkStatusResponse

Returned by GetPrivateLinkStatus.