# Agent access

Code on this page comes in TypeScript, Rust, and Python. The same page with one language only: [Python](https://docs.laserdata.com/md/python/agents.md), [TypeScript](https://docs.laserdata.com/md/typescript/agents.md), [Rust](https://docs.laserdata.com/md/rust/agents.md).

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](/laser-sdk/connect) and Iggy clients connecting straight to the deployment |
| LaserData API key | A secret sent in the `ld-api-key` header | The [REST API](/api), the [Laser CLI](/cli), the [MCP servers](/mcp), and the [data access proxy](#the-data-access-proxy). It turns into a connection string with [three REST calls](#from-an-api-key-to-a-connection-string) |

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](/laser-sdk) | Connection string | An [access rule](/networking/access-rules) 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) | API key | None | Organizations, deployments, credentials, access rules, configuration, telemetry |
| [Laser CLI](/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](/mcp) | API key | None | The REST operations as MCP tools: `https://api.laserdata.cloud/mcp` and `{supervisor_url}/mcp` |
| [Deployment data MCP](/mcp#deployment-data) | 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](#the-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](#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 |

1. `GET https://api.laserdata.cloud/tenants` returns a list with the key's one organization. Take its `id`.
2. `GET https://api.laserdata.cloud/tenants/{tenant_id}/deployments?results=100` lists every deployment the key can read, across every workspace and environment, under `items`, newest first. Each has `id`, `name`, `supervisor_url`, and the workspace and environment it belongs to. The list comes one page at a time with `page` and `total_pages`, so add `&page=2` and so on until `page` equals `total_pages`. Pick the deployment by its exact `name` or `id`. Use its `supervisor_url` for the next call and never build a host name yourself.
3. `GET {supervisor_url}/deployments/{deployment_id}/credentials` returns `connection_string`, exactly what `connect()` 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.

**TypeScript**

```ts
// 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()
```

**Rust**

```rust
// 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())
}
```

**Python**

```python
# 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](/laser-sdk/workflow), [Memory](/laser-sdk/memory), and [Sessions](/laser-sdk/session). 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](/api/deployments#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](/api/deployments#get-deployment-main-api) 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](/api/deployments#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](/api/deployments#rotate-deployment-credentials). Every credentials read and every rotation is written to the [audit log](/security/audit-compliance).

## 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](/laser-sdk/connect) has every option.

## The network path

A deployment on LaserData Cloud admits a direct connection only from addresses its [access rules](/networking/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 needs `deployment:access:manage` and suits an agent or a CI job whose address is not known in advance. See [Admit your address](#admit-your-address).
* **A rule for known addresses.** [Create an access rule](/networking/access-rules) 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/0` and `iggy_tcp` admits 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 as `streams`, with the `ld-api-key` header.
* Reading needs `deployment:read`. Creating, changing, or deleting resources, sending messages, and polling with automatic offset commits need `deployment:manage`.
* The [deployment data MCP endpoint](/mcp#deployment-data) 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 `504` and 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](/api/deployments#update-data-access) turns it on or off. Every detail of the relay, including its error codes, is in [Data access through LaserData](/deployments/warden#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](#admit-your-address) 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 |

- [Connect](/laser-sdk/connect): Connection strings, TLS, timeouts, and environment variables
- [MCP servers](/mcp): Connect an MCP client with an API key
- [Access rules](/networking/access-rules): Admit addresses per protocol
- [AI agents](/laser-sdk/ai-agents): Machine-readable entry points and task guides

Source: https://docs.laserdata.com/agents
