Authentication

Authenticate requests, restrict API keys, and distinguish tenant keys from user sessions

API Variables

ld-api-key

{tenant_id}

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

Use ld-api-key for programmatic access to tenant and deployment APIs. The Console also supports user sessions. Public pricing and schema discovery do not require a key.

Request Header

bash

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

Every request authenticates the key. Missing, expired, or invalid keys return 401 Unauthorized. A valid key without the required permission returns 403 Forbidden.

Key Format

API keys are randomly generated secrets. The server stores only their hashes and cannot recover the original values. Copy the secret when the key is created.

Scopes and Permissions

A key receives permissions through a role. Roles grant access at these levels:

Scope	Description
Tenant	Cross-organization permissions, for example `member:read`, `api_key:manage`
Division	Resource permissions scoped to specific environments, for example `deployment:manage`, `deployment:config:read`

See Roles & Permissions for scope and precedence.

Assign an existing role or supply inline permissions to create a dedicated role for the key.

Rate Limiting

Each key has its own rate limit. Exceeding it returns 429 Too Many Requests, with the reset time in Retry-After.

IP Allowlisting

An optional IP allowlist restricts where a key can be used. Other IPs receive 403 Forbidden, even when the key is valid.

Change an existing key's allowlist through Update API Key Security. Recreating the key is not required.

Expiry

Keys must expire within 365 days. Expired keys return 401 Unauthorized. Create and distribute a replacement before the current key expires.

Error Reference

Status	Cause
`400 Bad Request`	Validation failed. Response includes `field_issues[]` with per-field details
`401 Unauthorized`	Key missing, malformed, expired, or revoked
`403 Forbidden`	Key valid but missing the required permission, or request from a blocked IP
`404 Not Found`	Resource does not exist or is not visible to this key
`429 Too Many Requests`	Per-key rate limit exceeded. Check `Retry-After`
`500 Internal Server Error`	Unexpected server failure

Error Envelope

Non-2xx responses use application/problem+json, based on RFC 7807:

{
  "type": "about:blank",
  "title": "Invalid Email",
  "code": "invalid_email",
  "reason": "Invalid email address",
  "instance": "8f4a2b6c9d1e4f3a8b5c7d9e0f1a2b3c",
  "field": "email",
  "field_issues": [
    {
      "code": "invalid_email",
      "reason": "malformed address",
      "path": "email"
    }
  ],
  "status": 400,
  "retryable": false,
  "resolution": "Correct the invalid fields or request body, then retry."
}

instance matches ld-request, a UUID written as 32 hexadecimal characters without separators.

Field	Description
`type`	RFC 7807 type URI for the error class. `about:blank` when no type is registered
`title`	Short human-readable title derived from `code` (acronyms capitalised)
`code`	Stable machine-readable error code (e.g. `invalid_email`, `tenant_not_found`, `insufficient_permissions`)
`reason`	Long-form human explanation of this occurrence
`instance`	Mirrors the `ld-request` response header. Quote this when filing a support ticket
`field`	Single field name when the error is bound to one field. Still emitted for back-compat
`field_issues`	Array of per-field issues for validation errors. Each entry has `code`, `reason`, and an optional dotted `path`. Omitted on non-validation errors
`status`	Mirror of the HTTP status code so agents can branch on the body without re-reading the response status
`retryable`	`true` for retryable conditions (`408`, `425`, `429`, `500`, `502`, `503`, `504`), `false` otherwise
`resolution`	Concrete recovery guidance for an automated client or operator

Validation failures return 400 with field_issues. Use these entries to show errors beside the relevant fields.

API Keys vs Console Sessions

OpenAPI declares tenant-scoped ld_api_key and browser-session session_cookie. Most endpoints accept either. User-scoped endpoints reject API keys, even keys created by the same user.

These requests return 403 Forbidden with code: api_key_not_allowed. Session-only operations include account reads and exports, sign-out, own-session lists, invitation acceptance or rejection, own invitations, and user activity. Tenant creation, leaving, and deletion also require a Console-issued cookie session.

Security Best Practices

Store secrets in AWS Secrets Manager, HashiCorp Vault, GitHub Secrets, or another secret store. Keep them out of source code and logs.
Grant only required permissions. Read-only automation can use deployment:read instead of an administrator role.
Use short expiry periods, such as 30-90 days, for CI keys.
Enable IP restrictions for long-lived keys used from fixed infrastructure.
Rotate without interruption by creating a replacement, updating consumers, and deleting the old key after the change.
Read the audit trail for API key operations.