Authentication

Contract Lucidity uses OAuth 2.0 client credentials for machine-to-machine API access. This allows external systems (Power Automate flows, custom integrations, CI/CD pipelines) to interact with the API without a user session.

Creating API Credentials

1. Log in as an administrator.
2. Navigate to Settings > Security > API Credentials.
3. Click Create Credential.
4. Enter a descriptive name (e.g., "Power Automate - Contract Upload").
5. Copy the Client ID and Client Secret immediately.

warning

The client secret is displayed only once. Store it securely in a vault or secret manager. If lost, delete the credential and create a new one.

Token Exchange

Exchange your client credentials for a JWT access token:

curl -X POST https://<your-instance>/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Field	Description
access_token	JWT used to authenticate API requests. Valid for 24 hours (1440 minutes).
refresh_token	Token used to obtain a new access token without re-submitting credentials. Valid for 30 days.
token_type	Always bearer.

Using the Token

Include the access token in the Authorization header on all subsequent API requests:

curl https://<your-instance>/api/v1/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Refreshing Tokens

When the access token expires, you have two options:

1. Re-authenticate with client credentials (simplest approach — repeat the token exchange above).
2. Use the refresh token by calling the same endpoint with the refresh token in place of client credentials.

For most integrations, re-authenticating with client credentials is the simplest and most reliable approach.

Security Best Practices

Practice	Recommendation
Storage	Store client secrets in a vault or secret manager — never in source code, environment files committed to version control, or client-side applications.
Rotation	Rotate credentials on a regular schedule (e.g., every 90 days).
Revocation	If a credential is compromised, delete it immediately in Settings > Security > API Credentials.
Least privilege	Create separate credentials for each integration so they can be revoked independently.
Transport	Always use HTTPS. Never send credentials or tokens over unencrypted connections.

Scopes (Future)

API credentials currently grant the same access level as the admin who created them. Fine-grained scopes that limit which endpoints a credential can access are planned for a future release.