Authentication

All API requests are authenticated with a bearer token over HTTPS. Requests over plain HTTP are rejected.

API keys

Create keys in Settings, API keys. Each key has a label, a set of scopes and an optional expiry. We store only a SHA-256 hash of the key; if you lose it, create a new one.

curl https://api.consciouslab.xyz/v1/me \
  -H "Authorization: Bearer $CL_API_KEY"

{
  "workspace": "ws_northwind",
  "key": { "id": "key_4410", "label": "ci-deploy", "scopes": ["events:write", "agents:run"] }
}

Scopes

Grant the narrowest set of scopes a key needs.

A request with a missing scope returns 403 with "code": "scope_missing" and the scope that was required.

Test and live keys

Keys prefixed cl_test_ act on test-mode data only. Payments in test mode never move money, robotics commands are sent only to simulated devices, and trading orders go to paper accounts.

OAuth for user-facing apps

If you are building an app that acts on behalf of ConsciousLab users in other workspaces, use OAuth 2.0 with PKCE instead of API keys. Register the app in Settings, Developer apps to get a client ID. The authorisation endpoint is https://consciouslab.xyz/oauth/authorize and the token endpoint is https://api.consciouslab.xyz/oauth/token. Access tokens last one hour; refresh tokens last 90 days and rotate on use.

Rotating keys

Rotate keys at least every 90 days, and immediately if one may have leaked.

1. Create a new key with the same scopes.
2. Deploy it alongside the old key and switch traffic.
3. Check Last used on the old key. When it has not been used for 24 hours, revoke it.

Revocation takes effect within five seconds in every region. If a key is posted publicly on GitHub, our secret scanning partner notifies us and we revoke it automatically and email the workspace owners.