Authentication

Every endpoint except health needs a credential. There are two, for two situations:

If a browser can open, you do not need a key. If one cannot, a key is the only way in.

Using a key#

Authorization: Bearer lc_...

No refreshing and no expiry to handle unless you set one. A key belongs to one organisation, so targetOrganisationId is optional on every call - it is inferred, and naming a different organisation is refused with CA003.

curl -X POST https://api.light-cloud.com/api/applications \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

What a key cannot do#

By design, not by configuration:

• Billing and organisation settings. No key, at any access level, can change a payment method, invite a member, or delete a workspace. Those need a signed-in person.
• Manage keys. The endpoints below are session-only. A leaked key cannot mint a replacement or widen its own access - not even its own listing.
• Reach another workspace. A key is bound to the organisation it was created in.

Plans#

Keys require a paid plan; creating one on a free plan returns 402. The entitlement is re-checked on every request, so a downgrade stops existing keys working rather than letting them outlive it.

This is a limit on unattended credentials, not on automation - the MCP server and the CLI work on every account and can do everything a key can, and more (a key can never touch billing). They just need a person to approve the initial sign-in, from any browser.

Create an API key#

curl -X POST https://api.light-cloud.com/api/api-keys/create \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetOrganisationId": "org_1Ab",
    "name": "GitHub Actions",
    "role": "admin",
    "expiresAt": "2027-08-28T00:00:00.000Z"
  }'

{
  "id": "key_3Wq8",
  "name": "GitHub Actions",
  "prefix": "lc_RdiJfPH9X",
  "role": "admin",
  "expires_at": "2027-08-28T00:00:00.000Z",
  "created_at": "2026-08-28T11:16:35.617Z",
  "secret": "lc_RdiJfPH9XmS2cA7vK1pQ0tZbN4eL8yG6uW3rD5oX9jH"
}

List API keys#

curl -X POST https://api.light-cloud.com/api/api-keys \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetOrganisationId": "org_1Ab"}'

[
  {
    "id": "key_3Wq8",
    "name": "GitHub Actions",
    "prefix": "lc_RdiJfPH9X",
    "role": "admin",
    "created_by": "usr_5Kd",
    "expires_at": null,
    "revoked_at": null,
    "last_used_at": "2026-08-28T09:41:02.000Z",
    "created_at": "2026-08-20T10:00:00.000Z"
  }
]

Revoke an API key#

curl -X POST https://api.light-cloud.com/api/api-keys/revoke \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetOrganisationId": "org_1Ab", "keyId": "key_3Wq8"}'

{ "revoked": true }

Revoke a key when the person who created it leaves, when the job it served is retired, or the moment you suspect it has leaked. A key without an expiry does not stop working on its own.

You can also do all of this in the console: left sidebar → your workspace → API keys.

Session tokens#

The console, the MCP server and the CLI use short-lived tokens rather than keys: an access token valid for 15 minutes, plus a refresh token valid for 30 days. Sessions started from a terminal (the device-code flow) are listed under Settings → Security → Connected devices, where they can be revoked.

Obtaining one happens in the browser, through the console. The MCP server does this for you; a person confirms the connection, and the tokens are written to ~/.lightcloud/credentials.json. Implementing that flow yourself is not a supported integration path - use an API key.

Refresh a session token#

curl -X POST https://api.light-cloud.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -H "X-Client-Type: cli" \
  -d "{\"refreshToken\": \"$REFRESH_TOKEN\"}"

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "9c1f4e2a7b..."
}

Retrieve the current user#

curl https://api.light-cloud.com/api/auth/profile \
  -H "Authorization: Bearer $SESSION_TOKEN"

{
  "id": "usr_5Kd",
  "email": "you@example.com",
  "first_name": "Ada",
  "organisations": [
    {
      "id": "org_1Ab",
      "name": "Acme Labs",
      "slug": "acme-labs",
      "role": "owner"
    }
  ]
}

Sign out#

curl -X POST https://api.light-cloud.com/api/auth/logout \
  -H "Authorization: Bearer $SESSION_TOKEN"

{ "message": "Successfully logged out" }

Two-factor accounts#

When an account has two-factor authentication enabled, signing in returns a short-lived pending token instead of a session, and a TOTP or recovery code exchanges it for the real one at POST /api/auth/login/mfa. The console and MCP server handle this.

API keys are unaffected - they are workspace credentials, not account credentials, and carry no second factor of their own. That is another reason they cannot touch billing or membership.

Related#