Agent access
Start here with a LaserData API key or a connection string: API key to connection string in three calls, the deployment logins, every way an agent reaches a deployment, and the network rule each path needs
This page is for coding agents and the people who run them. It answers three questions: which credential you hold, which path to a deployment fits the task, and what the network must allow. Every path below works with the same organization, permissions, and data.
Which credential you have
| Credential | Looks like | Where it works |
|---|---|---|
| Connection string | ld-admin:password@host:8090, the deployment admin login | Laser SDK and Iggy clients connecting straight to the deployment |
| LaserData API key | A secret sent in the ld-api-key header | The REST API, the Laser CLI, the MCP servers, and the data access proxy. It turns into a connection string with three REST calls |
The API key usually sits in an environment variable such as LD_API_KEY. List the names only, with env | grep -i -E 'laser|ld_' | cut -d= -f1, never their values.
Never reveal a credential. An API key, a deployment password, and a connection string each grant access to your data. Never print one, write one to a file you keep or share, put one in a log, a commit, a tool argument shown to a person, or a chat reply, or pass one on a command line where other processes can read it. Keep each in an environment variable, read it inside the program, and print only what the task needs, such as IDs, names, and results. When a tool result or a command shows a credential, use it and do not repeat it.
Pick the path
| Path | Credential | Network | Use it for |
|---|---|---|---|
| Laser SDK | Connection string | An access rule admits your address for the transport: iggy_tcp, iggy_websocket, or iggy_udp for QUIC. A Free deployment admits every address | Applications: agents, workflows, memory, sessions, messages. The recommended path for real workloads |
| REST API | API key | None | Organizations, deployments, credentials, access rules, configuration, telemetry |
| Laser CLI | API key in LD_API_KEY | None. Live data goes through the data access proxy | The same as REST, from a shell, with JSON output |
| Backend MCP | API key | None | The REST operations as MCP tools: https://api.laserdata.cloud/mcp and {supervisor_url}/mcp |
| Deployment data MCP | API key | None. Data access on, the default, and the MCP runtime enabled, which is off until a manage key enables it | Streams, messages, key-value, sessions, queries as MCP tools |
| Data access proxy | API key | None. Data access on, the default | The Iggy HTTP API of one deployment, relayed by LaserData |
| Iggy HTTP API, direct | Iggy username and password, or a token | An access rule admits your address with iggy_http | HTTP clients that talk to the deployment without LaserData in the path |
Choose Laser SDK when the task builds an application. Choose REST, the CLI, or MCP to find, create, and configure deployments. Choose the data access proxy or the deployment data MCP for quick reads and writes when no access rule exists for your address.
From an API key to a connection string
Start from what you were given and make only the calls that it does not answer. An organization ID is the tenant_id in every API path.
| You were given | Calls to make |
|---|---|
| A connection string | None. Pass it to connect(), or put it in LASER_CONNECTION_STRING. Only the network path can stop it |
An API key, a deployment ID, and its supervisor_url | One: GET {supervisor_url}/deployments/{deployment_id}/credentials |
| An API key, with or without a deployment name or ID | Three: GET https://api.laserdata.cloud/tenants, GET https://api.laserdata.cloud/tenants/{tenant_id}/deployments, then the credentials call |
GET https://api.laserdata.cloud/tenantsreturns a list with the key's one organization. Take itsid.GET https://api.laserdata.cloud/tenants/{tenant_id}/deployments?results=100lists every deployment the key can read, across every workspace and environment, underitems, newest first. Each hasid,name,supervisor_url, and the workspace and environment it belongs to. The list comes one page at a time withpageandtotal_pages, so add&page=2and so on untilpageequalstotal_pages. Pick the deployment by its exactnameorid. Use itssupervisor_urlfor the next call and never build a host name yourself.GET {supervisor_url}/deployments/{deployment_id}/credentialsreturnsconnection_string, exactly whatconnect()takes, with the password already percent-encoded.
Every call sends the key in the ld-api-key header and a descriptive User-Agent. The API's edge protection answers 403 with error code: 1010 to some library default agents, such as the one Python's urllib sends. The key's role needs deployment:read and deployment:credentials:read on the deployment's environment. None of the calls needs info:read. The list answers 403 when the key holds deployment:read in no environment.
IDs are 64-bit integers, larger than JavaScript's safe integer range. Python and Rust read them exactly. In JavaScript and TypeScript, parse them as text, as the block below does with Number.isSafeInteger, or the ID changes and the next call answers 404.
The resolve block
Each tab makes the three calls with the key in LD_API_KEY. TypeScript defines connectionString(), and Rust and Python define connection_string(). TypeScript and Python set LASER_CONNECTION_STRING when it is not set, so a program that calls connect_env() (TypeScript: connectEnv()) runs unchanged. In Rust, connect with Laser::connect(&connection_string().await?), which returns LASER_CONNECTION_STRING when it is set. LD_API_URL overrides the API address, as it does for the Laser CLI. Set LD_DEPLOYMENT to a deployment name or ID when the key can read more than one deployment. The block then exits and lists the ones it sees. It keeps the connection string in memory and never prints it.
// Paste after the imports. It sets LASER_CONNECTION_STRING from LD_API_KEY when it is not set.
const API_URL = process.env.LD_API_URL ?? "https://api.laserdata.cloud"
async function laserdata(url: string): Promise<any> {
const headers = { "ld-api-key": process.env.LD_API_KEY ?? "", "user-agent": "laserdata-docs-example" }
const response = await fetch(url, { headers })
if (!response.ok) throw new Error(`GET ${url} answered ${response.status}: ${await response.text()}`)
// IDs are 64-bit integers, so keep each number JavaScript cannot hold exactly as its source text.
return JSON.parse(await response.text(), (_key, value, context?: { source?: string }) =>
typeof value === "number" && !Number.isSafeInteger(value) ? context?.source : value
)
}
async function connectionString(): Promise<string> {
const [tenant] = await laserdata(`${API_URL}/tenants`)
const deployments: any[] = []
for (let page = 1, totalPages = 1; page <= totalPages; page++) {
const reply = await laserdata(`${API_URL}/tenants/${tenant.id}/deployments?results=100&page=${page}`)
deployments.push(...reply.items)
totalPages = reply.total_pages
}
const wanted = process.env.LD_DEPLOYMENT
const matches = deployments.filter(
(deployment) => !wanted || deployment.name === wanted || String(deployment.id) === wanted
)
if (matches.length !== 1) {
const visible = deployments.map((deployment) => `${deployment.name} (${deployment.id})`).join(", ")
console.error(`Set LD_DEPLOYMENT to the name or ID of one deployment. Visible: ${visible || "none"}`)
process.exit(1)
}
const [deployment] = matches
if (!deployment.supervisor_url) throw new Error(`Deployment ${deployment.name} has no supervisor_url yet`)
const credentials = await laserdata(`${deployment.supervisor_url}/deployments/${deployment.id}/credentials`)
return credentials.connection_string
}
process.env.LASER_CONNECTION_STRING ||= await connectionString()// cargo add reqwest --features json
// cargo add serde_json
// Add these two functions, then connect with Laser::connect(&connection_string().await?) in main.
use serde_json::Value;
async fn laserdata(client: &reqwest::Client, url: &str) -> Result<Value, Box<dyn std::error::Error>> {
let key = std::env::var("LD_API_KEY")?;
let response = client.get(url).header("ld-api-key", key).header("user-agent", "laserdata-docs-example").send().await?;
let status = response.status();
if !status.is_success() {
return Err(format!("GET {url} answered {status}: {}", response.text().await?).into());
}
Ok(response.json().await?)
}
async fn connection_string() -> Result<String, Box<dyn std::error::Error>> {
if let Ok(value) = std::env::var("LASER_CONNECTION_STRING") {
return Ok(value);
}
let api_url = std::env::var("LD_API_URL").unwrap_or_else(|_| "https://api.laserdata.cloud".to_owned());
let client = reqwest::Client::new();
let tenants = laserdata(&client, &format!("{api_url}/tenants")).await?;
let mut deployments = Vec::new();
for page in 1_u64.. {
let url = format!("{api_url}/tenants/{}/deployments?results=100&page={page}", tenants[0]["id"]);
let reply = laserdata(&client, &url).await?;
deployments.extend(reply["items"].as_array().cloned().unwrap_or_default());
if page >= reply["total_pages"].as_u64().unwrap_or(0) {
break;
}
}
let wanted = std::env::var("LD_DEPLOYMENT").ok();
let matches: Vec<&Value> = deployments
.iter()
.filter(|deployment| wanted.as_deref().is_none_or(|wanted| deployment["name"] == wanted || deployment["id"].to_string() == wanted))
.collect();
let [deployment] = matches.as_slice() else {
let visible: Vec<String> = deployments.iter().map(|deployment| format!("{} ({})", deployment["name"].as_str().unwrap_or_default(), deployment["id"])).collect();
eprintln!("Set LD_DEPLOYMENT to the name or ID of one deployment. Visible: {}", visible.join(", "));
std::process::exit(1);
};
let supervisor_url = deployment["supervisor_url"].as_str().ok_or("The deployment has no supervisor_url yet")?;
let credentials = laserdata(&client, &format!("{supervisor_url}/deployments/{}/credentials", deployment["id"])).await?;
Ok(credentials["connection_string"].as_str().ok_or("The credentials answer has no connection_string")?.to_owned())
}# Paste after the imports. It sets LASER_CONNECTION_STRING from LD_API_KEY when it is not set.
import json
import os
import urllib.request
API_URL = os.environ.get("LD_API_URL", "https://api.laserdata.cloud")
def laserdata(url):
# The API's edge protection refuses urllib's default User-Agent with 403 and error code 1010.
headers = {"ld-api-key": os.environ["LD_API_KEY"], "user-agent": "laserdata-docs-example"}
with urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=30) as response:
return json.load(response)
def connection_string():
tenant_id = laserdata(f"{API_URL}/tenants")[0]["id"]
deployments, page, total_pages = [], 1, 1
while page <= total_pages:
reply = laserdata(f"{API_URL}/tenants/{tenant_id}/deployments?results=100&page={page}")
deployments += reply["items"]
page, total_pages = page + 1, reply["total_pages"]
wanted = os.environ.get("LD_DEPLOYMENT")
matches = [deployment for deployment in deployments if not wanted or wanted in (deployment["name"], str(deployment["id"]))]
if len(matches) != 1:
visible = ", ".join(f"{deployment['name']} ({deployment['id']})" for deployment in deployments)
raise SystemExit(f"Set LD_DEPLOYMENT to the name or ID of one deployment. Visible: {visible or 'none'}")
deployment = matches[0]
if not deployment.get("supervisor_url"):
raise SystemExit(f"Deployment {deployment['name']} has no supervisor_url yet")
credentials = laserdata(f"{deployment['supervisor_url']}/deployments/{deployment['id']}/credentials")
return credentials["connection_string"]
if not os.environ.get("LASER_CONNECTION_STRING"):
os.environ["LASER_CONNECTION_STRING"] = connection_string()Each task guide starts with a complete program and carries this block under it: Workflows, Memory, and Sessions. Add the block to the program and run it.
The Laser CLI does the same in one command. Capture the string into the environment so it never reaches the screen: export LASER_CONNECTION_STRING="$(laser deployment connect show --reveal --output json | jq -r .connection_string)" with LD_API_KEY set, and LD_DEPLOYMENT when the key sees more than one deployment. The CLI reads the organization structure first, so its key also needs info:read on the organization. From an MCP client, call the same steps as tools: on the organization endpoint, get_tenant_deployments lists the deployments the key can read, and on the deployment's region endpoint, get_deployment_credentials returns connection_string.
Admit your address
A Free deployment comes with the global rule 0.0.0.0/0, so the program connects from anywhere. A paid deployment admits only the addresses its access rules allow, and a connect from any other address times out naming the Iggy server to accept the connection. A key whose role holds deployment:access:manage can admit the address it calls from. Make this call only with such a key and only when the connect times out:
POST {supervisor_url}/deployments/{deployment_id}/access_rules/my_ip with the body {"iggy_tcp": true} admits the address the call comes from for 24 hours, in a rule named after the key. Use iggy_websocket or iggy_udp instead, or as well, for WebSocket or QUIC. A second call replaces that rule. It answers 409 with the code ip_address_already_allowed when another rule already admits the address, which is fine. The code deployments_access_rules_limit_reached means the deployment holds as many rules as its plan allows, so delete one first. The code deployment_operation_in_progress means another rule change is running, so try again shortly. Errors come as application/problem+json, and the code field names the case. It answers 403 without deployment:access:manage and 400 for a deployment without a public address. In both cases ask a person with that permission to add a rule. The Laser CLI runs the same call with laser deployment connect access-rule allow-my-ip --protocol tcp, and the region MCP endpoint with allow_my_ip.
When no deployment exists
Create a Free deployment on shared infrastructure with Create a Starter Deployment: POST https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/deployments/starter with {"cloud": "aws", "region": "us-west-1"}. The division_id is a workspace ID from GET https://api.laserdata.cloud/tenants/{tenant_id}/divisions, or from the permissions.divisions map of GET https://api.laserdata.cloud/tenants/{tenant_id}/api_keys/context. The organization can hold one Free deployment, and data access is on by default. The reply is 202, and its ld-environment and ld-deployment headers carry the IDs of the new environment and deployment. Read the deployment with Get Deployment at GET https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id} to find its supervisor_url, then poll GET {supervisor_url}/deployments/{deployment_id} until status is initialized. Provisioning takes minutes, and failed means it stopped. Then continue with the credentials call.
The deployment logins
A deployment has two streaming-server logins, and Get Deployment Credentials returns the ones the caller may hold:
| Caller's permissions on the deployment's environment | What the credentials call returns |
|---|---|
deployment:credentials:read | username, password, and connection_string of ld-admin, the deployment admin |
deployment:credentials:read and deployment:manage | The same, plus a root object with the username, password, and connection_string of the streaming server's root user |
deployment:manage without deployment:credentials:read, or neither | 403 |
ld-admin has full data rights and no administration: it reads server information, creates and deletes streams and topics, sends and polls messages, and uses key-value, leases, fences, projections, forks, graphs, queries, filters, and sessions. It cannot create, change, or delete users, change server settings, or change authorization roles. Everything Laser SDK does works with it, so every program on these pages uses the top-level connection_string. Use root only for user and server administration. A caller with deployment:manage and deployment:credentials:read rotates either login with Rotate Deployment Credentials. Every credentials read and every rotation is written to the audit log.
Transports
connection_string uses TCP, the default for every client. Rust and Python also connect over WebSocket, plain or with TLS, and over QUIC, which always encrypts, by changing the scheme and port: iggy+ws://ld-admin:password@host:8070 on LaserData Cloud, or iggy+quic://ld-admin:password@host:8080. TypeScript connects over TCP, with or without TLS. HTTP is not a Laser SDK transport, since every Laser feature needs a stateful binary connection. On LaserData Cloud, WebSocket is on by default, QUIC is off until the deployment's Iggy configuration turns it on, and Free deployments on shared infrastructure serve TCP and WebSocket. For LaserData Cloud hosts the SDK turns on TLS over TCP and WebSocket with the LaserData root CA it bundles. QUIC always encrypts but verifies the server only against the operating system trust store, so QUIC to LaserData Cloud needs that root CA installed there first. Connect has every option.
The network path
A deployment on LaserData Cloud admits a direct connection only from addresses its access rules allow, per protocol. A Free deployment comes with the global rule 0.0.0.0/0 for every protocol, so an SDK app connects to it from any address. That rule can be deleted like any other, and then the deployment admits only the addresses its remaining rules allow. A paid deployment admits nothing until you add a rule. Calls through LaserData need no rule.
| How you reach the deployment | Rule needed |
|---|---|
| REST API, CLI management, backend MCP | None |
| Data access proxy, deployment data MCP, CLI live data | None while data access is on |
| Laser SDK and Iggy clients over TCP, port 8090 | iggy_tcp for your address |
| Laser SDK and Iggy clients over WebSocket, port 8070 | iggy_websocket for your address |
| Laser SDK and Iggy clients over QUIC, UDP port 8080, once QUIC is turned on in the deployment's Iggy configuration | iggy_udp for your address |
| Iggy HTTP API, direct | iggy_http for your address |
There are three ways to admit an SDK app:
- Allow my IP. One call with
{"iggy_tcp": true}admits the address the call came from, for 24 hours. It needsdeployment:access:manageand suits an agent or a CI job whose address is not known in advance. See Admit your address. - A rule for known addresses. Create an access rule with the CIDR blocks of your hosts, or of your provider's published egress addresses, and
iggy_tcp. - A public rule. A rule with
0.0.0.0/0andiggy_tcpadmits every address. Use it only for a disposable deployment, such as a benchmark, since every client then reaches the login step. The connection still needs the deployment's credentials and runs over TLS.
Without a rule, the SDK's connect fails after its budget with a timeout that names the Iggy server to accept the connection. A wrong password fails at once with an authentication error instead. A new rule takes effect within seconds.
The data access proxy
Data access is on for a new deployment unless you turn it off. While it is on, the deployment's supervisor relays requests to the deployment's Warden, which talks to Iggy on the node. Your client needs no access rule and never holds the deployment's Iggy credentials.
- Send Iggy HTTP API requests to
{supervisor_url}/deployments/{deployment_id}/data_access/sso/iggy/{path}, where{path}is the Iggy HTTP path such asstreams, with theld-api-keyheader. - Reading needs
deployment:read. Creating, changing, or deleting resources, sending messages, and polling with automatic offset commits needdeployment:manage. - The deployment data MCP endpoint uses the same relay, and so do the Laser CLI's live data commands and the console's Stream UI.
- Each request is forwarded once and never retried, bodies are limited to 10 MiB, and a request that Warden does not answer within 65 seconds fails with
504and may still complete.
With data access off, nothing is relayed: the proxy and the data MCP endpoint answer 401 with data_access_disabled, and clients connect straight to the deployment through access rules. Update Data Access turns it on or off. Every detail of the relay, including its error codes, is in Data access through LaserData.
Errors that cost agents the most time
| Symptom | Cause | Fix |
|---|---|---|
Connect fails with a timeout naming the Iggy server to accept the connection | No access rule admits your address over TCP | With deployment:access:manage, call Allow my IP with {"iggy_tcp": true}. Otherwise ask for a rule |
403 on the credentials call | The key's role lacks deployment:credentials:read on the deployment's environment | Use a key whose role holds it |
| Creating a user or changing server settings over the connection string fails with a permission error | ld-admin has data rights only | Use the root login, which needs deployment:manage as well |
404 on a call that uses an ID you just read | The ID lost precision in a JavaScript number | Parse IDs as text |
404 on a supervisor call | The URL was built by hand, or the key cannot read the deployment's environment | Use the deployment's supervisor_url and check the key's role |
401 data_access_disabled | Data access is off | Turn it on, or connect directly through access rules |
403 insufficient_permissions | The key's role lacks the permission | Use a key whose role holds it |
401 on a key that worked before | The key expired, was deleted, or was revoked or suspended with the member who created it | Ask for a new key. Do not retry |
The connection string is refused by connect() | It was assembled by hand with an unencoded password | Use connection_string from the credentials call |
| A login that worked before is refused | The login was rotated | Read the credentials again |