Authentication

You can authenticate to the Light API using API keys or the OAuth 2.0 user flow.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail, and so will requests without authentication.

Make sure your HTTP client follows redirects and forwards the Authorization header, as some endpoints may redirect to other URLs.

# API keys

To create an API key, log in to Light, navigate to Settings > API Keys and click Create key. Copy and securely store the generated key — it is not shown again.

Light API keys are linked to roles the same way user accounts are. The roles assigned to the API key determine what actions the key can perform.

To use an API key, include the Authorization header on your requests with the Basic scheme:

Authorization: Basic YOUR_API_KEY

Send the key exactly as Light issued it. Unlike standard HTTP Basic authentication there is no username:password pair to base64-encode — the value after Basic is the key itself.

Here is a complete request, listing customers. The key below is made up — yours comes from Settings > API Keys:

GET /v1/customers HTTP/1.1
Host: api.light.inc
Authorization: Basic live_4f8Kq2mXpR7vN3wZ6yB1tD5s
Accept: application/json

The same call, ready to run — swap in your own key:

curl "https://api.light.inc/v1/customers" \
  -H "Authorization: Basic live_4f8Kq2mXpR7vN3wZ6yB1tD5s"

const res = await fetch("https://api.light.inc/v1/customers", {
  headers: { Authorization: `Basic ${process.env.LIGHT_API_KEY}` },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.light.inc/v1/customers",
    headers={"Authorization": f"Basic {os.environ['LIGHT_API_KEY']}"},
)
data = res.json()

Never expose an API key in client-side code, a public repository or a shared document. Use environment variables or a secrets manager.

# OAuth 2.0

Note. Contact Light support at help@light.inc to set your account up for the OAuth 2.0 flow.

Once your account is set up you receive a client_id and client_secret. You also give Light a redirect URI, where users are sent after they authorise your application.

To start the OAuth 2.0 authorization code flow, open:

https://api.light.inc/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

You can also pass an optional state parameter. See the OAuth 2.0 spec for what it is for.

# Exchanging the authorization code for an access token

After the user authorises your application they are redirected back to your redirect URI with an authorization code. Exchange it for an access token by POSTing to the token endpoint:

curl -X POST https://api.light.inc/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

The response includes an access_token, which authenticates your API requests. Send it in the Authorization header with the Bearer scheme:

Authorization: Bearer YOUR_ACCESS_TOKEN

The response also includes refresh_token and expires_in. Store all three securely so you can refresh the access token when it expires.

# Refreshing access tokens

When your access token expires, use the refresh token to get a new one:

curl -X POST https://api.light.inc/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

The response contains a new access_token, refresh_token and expires_in. Use the new access token for subsequent requests.

Warning. Replace your stored refresh token with the new one from the response — the old one is invalidated after use.