Authentication
Use a CalmLens SDK on your server. Configure it with a project API key and project ID; the SDK sends the authentication header for you. Keep direct HTTP calls for integrations that cannot use an SDK; see the API reference.
const page = await client.assets.list({ pageIndex: 0 });
Create and protect keys
Create keys under Portal › Developer › API Keys. The complete key is shown only when it is created.
- Keep keys on a server or in a secret manager, never in browser bundles or source control.
- Give each integration its own named key so it can be revoked independently.
- Treat a revoked or expired key as unusable and rotate clients before expiration.
- A key is project-scoped. The project in the URL must match the key's project.
Rotate a key
- Create a replacement with the permissions your integration needs.
- Update the secret in your server environment and deploy it.
- Verify a request succeeds with the replacement, then revoke the old key.
Choose permissions
| Integration needs | Grant |
|---|---|
| Submit content | Upload assets in the relevant project or folders. |
| Read reports | View assets in the relevant scope. |
| Fetch private files | Download assets. |
| Give browsers private access | Permission to create signed sharing URLs. |
Use Members and permissions for custom folder scopes.
CDN access
Public assets need no authentication. For private assets, prefer a short-lived signed URL in browsers and other untrusted clients.
Enable Download assets (assets:download) when creating or editing an API key to allow direct private CDN reads within its project. Keys without this permission need a short-lived signed URL or an authenticated owner session.
Authentication failures
API errors use an HTTP status and a JSON body containing a stable code, a human-readable message, and usually a traceId. Log the trace ID when contacting support, but branch application logic on code rather than message text.
| Error | What to do |
|---|---|
| 401 auth/missing-token | Send your project API key in the X-Api-Key header. |
| 401 auth/invalid-api-key | The key is unknown, revoked or expired. Check for typos or whitespace, or create a new key under Portal › Developer › API Keys. |
| 403 auth/project-mismatch | The key belongs to a different project. Use a key created for the project in the URL, or the project that owns the asset or folder. |
Do not retry 401 or 403 responses with the same key; fix the configuration first.