API Keys

Create, list, update, and delete API keys for programmatic access to the LaserData Cloud API.

API Variables

ld-api-key

{tenant_id}

Set variables to auto-fill all examples and run requests in-browser.

API keys provide programmatic access for CI/CD, CLIs, Terraform providers, and other non-interactive integrations. All endpoints use the main API at https://api.laserdata.cloud.

Required permissions: api_key:read to list, api_key:manage to create/update/delete.

Create an API Key

With an Existing Role

POST

/tenants/{tenant_id}/api_keys

Create a new API key assigned to an existing role.

bash

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
}'

With Inline Permissions

POST

/tenants/{tenant_id}/api_keys

Create a new API key with inline permissions (a dedicated role is created automatically).

bash

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"]
  }
}'

Field	Required	Description
`name`	Yes	Human-readable name
`expiry_at`	Yes	Expiration timestamp (ISO 8601, max 365 days)
`role_id`	No*	Existing role to assign
`permissions`	No*	Inline permissions object (creates a dedicated role)
`division_id`	No	Scope key to a specific division
`validate_ip`	No	Enable IP allowlisting (default `false`)
`allowed_ips`	No	IP addresses or CIDRs to allowlist (requires `validate_ip: true`)

*Provide either role_id or permissions, not both.

The response includes the full API key secret, so copy it immediately. It cannot be retrieved again.

{
  "id": 1,
  "name": "ci-deploy-key",
  "secret": "ld_api_key_abcdef...",
  "role_id": 67890,
  "expiry_at": "2026-06-01T00:00:00Z",
  "created_at": "2025-01-15T10:30:00Z"
}

List API Keys

GET

/tenants/{tenant_id}/api_keys

List all API keys in the tenant. Secrets are never returned in list responses.

bash

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

{
  "items": [
    {
      "id": 1,
      "name": "ci-deploy-key",
      "role_id": 67890,
      "role_name": "deployer",
      "division_id": 123,
      "division_name": "production",
      "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
}

Self-Introspection

GET

/tenants/{tenant_id}/api_keys/context

Return the calling key's role, division scope, IP-allowlist state, expiry, and resolved permission set. Requires no specific permission - the key authenticating the request is sufficient.

bash

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

{
  "id": 1,
  "division_id": null,
  "division_name": null,
  "user_id": 608123456789012345,
  "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",
  "permissions": {
    "tenant": ["info:read", "deployment:manage"],
    "divisions": { "...": "..." }
  }
}

Use this endpoint to verify a key authenticates and to discover its scope, instead of probing arbitrary protected endpoints. A 403 from any other endpoint cannot disambiguate "key invalid" from "key lacks the required permission"; this endpoint is gated to API-key sessions only and never returns 403 for permission reasons.

Update Security Settings

PUT

/tenants/{tenant_id}/api_keys/{api_key_id}/security

Update IP allowlist settings on an existing key without recreating it.

bash

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/24"]
}'

Delete an API Key

DELETE

/tenants/{tenant_id}/api_keys/{api_key_id}

Revoke and delete an API key. Access is blocked immediately, no grace period.

bash

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

API Keys

Create an API Key

With an Existing Role

With Inline Permissions

List API Keys

Self-Introspection

Update Security Settings

Delete an API Key

API Keys Guide

Authentication

Roles & Permissions

On this page