API Keys

API keys provide programmatic access to the LaserData Cloud API for CI/CD pipelines, CLIs, Terraform providers, and other non-interactive integrations. They use the same permission model as interactive sessions.

How It Works

1. Create an API key in the Console, selecting a role and optional IP restrictions
2. A secret is generated and shown once - it cannot be retrieved again
3. Include the secret in the ld-api-key header on every request
4. The platform validates the key, checks rate limits and IP allowlists, and applies the role's permissions

Creating an API Key

From the Console

1. Navigate to your tenant's API Keys page
2. Click Create API Key
3. Enter a name for the key
4. Choose one of:
   • Existing role - assign any role already defined in your tenant
   • Inline permissions - define permissions directly (a dedicated role is created automatically)
5. Set an expiration date (maximum 365 days)
6. Click Create
7. Copy the secret immediately - it will not be shown again

With Inline Permissions

When creating with inline permissions, define tenant, division, and environment grants directly. The role is created behind the scenes and tied to the key.

{
  "name": "monitoring-key",
  "expiry_at": "2026-06-01T00:00:00Z",
  "permissions": {
    "tenant": ["info:read", "member:read"],
    "division": ["environment:read"],
    "environment": ["deployment:read", "deployment:telemetry:read"]
  }
}

permissions.environment is the global environment slot - applies to every environment in every division. Use permissions.divisions[id].environment for per-division defaults and permissions.divisions[id].environments[env_id] for per-environment overrides. See Roles & Permissions for the full precedence rules.

Security

IP Allowlisting

Restrict an API key to specific IP addresses for additional security. When enabled, requests from IPs not in the allowlist receive a 403 response. You can update IP restrictions on existing keys without recreating them.

The number of allowed IPs per key is plan-gated:

Managing API Keys

From the API Keys page you can:

• View all keys with their name, role, expiry, and creation date
• Update security settings (IP allowlisting) on existing keys
• Delete keys - access is revoked immediately

Required permission: api_key:manage (create, delete, update) or api_key:read (list)

All API key operations are recorded in the audit log.

API Reference

Create an API Key with a Role

curl -X POST https://api.laserdata.cloud/tenants/{tenant_id}/api_keys \
  -H "ld-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy-key",
    "role_id": 67890,
    "division_id": 123,
    "expiry_at": "2026-06-01T00:00:00Z",
    "validate_ip": false
  }'

Provide either role_id (use an existing role) or permissions (inline permissions - a dedicated role is created automatically), not both. division_id scopes the key to a specific division.

Create an API Key with Inline Permissions

curl -X POST https://api.laserdata.cloud/tenants/{tenant_id}/api_keys \
  -H "ld-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "monitoring-key",
    "expiry_at": "2026-06-01T00:00:00Z",
    "validate_ip": true,
    "allowed_ips": ["10.0.0.1"],
    "permissions": {
      "tenant": ["info:read", "member:read"],
      "division": ["environment:read"]
    }
  }'

List API Keys

curl https://api.laserdata.cloud/tenants/{tenant_id}/api_keys \
  -H "ld-api-key: YOUR_API_KEY"

{
  "items": [
    {
      "id": 1,
      "division_id": 123,
      "division_name": "production",
      "user_id": 1,
      "role_id": 67890,
      "role_name": "deployer",
      "name": "ci-deploy-key",
      "validate_ip": false,
      "allowed_ips": [],
      "expiry_at": "2026-06-01T00:00:00Z",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "total_results": 1,
  "total_pages": 1
}

Update Security Settings

curl -X PUT https://api.laserdata.cloud/tenants/{tenant_id}/api_keys/{api_key_id}/security \
  -H "ld-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "validate_ip": true,
    "allowed_ips": ["10.0.0.1", "192.168.1.0"]
  }'

Delete an API Key

curl -X DELETE https://api.laserdata.cloud/tenants/{tenant_id}/api_keys/{api_key_id} \
  -H "ld-api-key: YOUR_API_KEY"