Authentication¶

The LightPane API uses a unified authentication model. Every request resolves to an access grant — a record that determines which cloud accounts and services the caller can access.

Authentication methods¶

Three methods are supported, evaluated in this order:

Set automatically when you log in to app.lightpane.cloud. Session tokens are short-lived (4-8 hours) and grant access to all cloud accounts in your profile.

You do not need to manage session tokens directly. The browser sends the cookie automatically.

2. Bearer token¶

Pass an access key in the Authorization header:

Authorization: Bearer csl_ak_7Fj3kL9mN2pQ4rS6tU8vW0xY1zA3bC5dE7fG9hI

Bearer tokens are used for:

Embed keys (csl_em_) — embedded web pages
API keys (csl_ak_) — scripts, CI/CD, Excel/Power Query
Demo keys (csl_dm_) — public demo pages

Each bearer token resolves to an access grant with specific cloud bindings, service scope, and constraints.

3. Anonymous fallback¶

If no valid credential is present, the API falls back to the platform demo account. This allows the LightPane marketing site to show live demos without authentication. Anonymous access is read-only against the demo account only.

Token resolution flow¶

Request arrives
├── Cookie present?
│   ├── Yes → Verify HMAC signature → Check session table
│   │   ├── Valid → Full access to user's cloud accounts
│   │   └── Invalid → Continue to bearer token check
│   └── No → Continue to bearer token check
│
├── Authorization: Bearer header present?
│   ├── Yes → SHA-256 hash the token → Look up in access grants table
│   │   ├── Found + not revoked + not expired
│   │   │   ├── Validate constraints (origin, IP, rate limit)
│   │   │   │   ├── Pass → Access granted with grant's bindings and scope
│   │   │   │   └── Fail → 403 Forbidden (constraint violation)
│   │   │   └──
│   │   └── Not found / revoked / expired → 401 Unauthorized
│   └── No → Continue to anonymous
│
└── No credentials
    └── Anonymous → Demo account access only

Token storage¶

Raw tokens are never stored by LightPane. Only the SHA-256 hash is saved in the access grants table. When you create a key, the raw token is shown once and cannot be retrieved again.

Copy your token at creation time

The raw token is displayed once when you create an access key. If you lose it, you must revoke the key and create a new one.

Constraint validation¶

Bearer tokens can have server-side constraints that are checked on every request:

Constraint	Validated against	Use case
`allowed_origins`	`Origin` or `Referer` request header	Embed keys — restrict to your domains
`allowed_ips`	Source IP from API Gateway	CI/automation — restrict to known IPs
`rate_limit_rpm`	Per-token request counter	All key types — prevent abuse
`max_batch_size`	Number of services in the request	Embed/demo — limit cost per request
`require_referer`	Presence of `Referer` header	Embed keys — block direct curl access

If a constraint is violated, the API returns 403 with a specific error message. See Error Handling for details.

Scope¶

Each access grant has two scope dimensions:

Cloud bindings — which cloud accounts the token can access. A token can only access the specific AWS accounts, GCP projects, or Azure subscriptions it was created for.

Service scope — which services the token can discover. Set to ["*"] for all services, or a specific list like ["ec2", "s3", "lambda_functions"].

If a request asks for a service outside the token's scope, the API returns 403.