Authentication

Lucid Green APIs use OAuth2 for authentication. Each OAuth2 user account is associated with a Brand and Company, and may have information access restrictions based on the Brand and Company to which it belongs.

Your Client ID and Client Secret will be provided by Lucid Green during integration setup. Keep these credentials secure and never expose them in client-side code or public repositories.

Obtaining an Access Token

To authenticate, request an access token from the OAuth2 token endpoint using the Client Credentials grant type.

The token endpoint depends on which product you are integrating with (see Server Hosts for all available environments):

Product	Token URL
LucidSource	`https://source.lucidgreen.io/o/token/`
LucidRetail	`https://retail.lucidgreen.io/o/token/`

cURL Example

curl -X POST https://source.lucidgreen.io/o/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Python Example

import requests

response = requests.post(
    "https://source.lucidgreen.io/o/token/",
    data={
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
    },
)

token_data = response.json()
access_token = token_data["access_token"]

Token Response

A successful token request returns:

{
    "access_token": "your_access_token_here",
    "token_type": "Bearer",
    "expires_in": 36000,
    "scope": "read write"
}

Field	Description
`access_token`	The token to include in API requests
`token_type`	Always `Bearer`
`expires_in`	Token lifetime in seconds
`scope`	Granted permissions

Using the Access Token

Include the access token in the Authorization header of every API request:

curl https://source.lucidgreen.io/api/v1.5/products/ \
  -H "Authorization: Bearer your_access_token_here"

response = requests.get(
    "https://source.lucidgreen.io/api/v1.5/products/",
    headers={"Authorization": f"Bearer {access_token}"},
)

Token Expiration

Access tokens expire after the duration specified in expires_in (typically 10 hours). When a token expires, the API returns a 401 Unauthorized response. Your integration should handle this by requesting a new token and retrying the request.

def get_access_token(client_id, client_secret, token_url):
    response = requests.post(
        token_url,
        data={
            "grant_type": "client_credentials",
            "client_id": client_id,
            "client_secret": client_secret,
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]

Note

Avoid requesting a new token before every API call. Instead, cache the token and only refresh it when you receive a 401 response or when the expires_in duration has elapsed.

Error Responses

HTTP Code	Cause
`400 Bad Request`	Missing or invalid parameters (e.g., wrong `grant_type`)
`401 Unauthorized`	Invalid `client_id` or `client_secret`, or expired access token

Test Environments

For development and testing, use the test environment token endpoints:

Product	Test Token URL
LucidSource	`https://source-test.lucidgreen.io/o/token/`
LucidRetail	`https://retail-test.lucidgreen.io/o/token/`

Test environment credentials are provided separately during integration setup. See Server Hosts for details.