Auth.md

You are an agent. The LightLead API supports OAuth 2.0 agentic registration: discover → register a client → authenticate with the Authorization Code + PKCE flow → call the API with a bearer token. Follow the steps in order.

Step 1 — Discover

Machine-readable discovery metadata:

• Protected Resource Metadata: https://agents.lightlead.space/.well-known/oauth-protected-resource
• Authorization Server metadata: https://agents.lightlead.space/.well-known/oauth-authorization-server
• This skill document: https://agents.lightlead.space/auth.md

Step 2 — Register a client

Request a client (or machine account) from your LightLead account administrator; credentials are issued to approved integrations. If dynamic registration is enabled, register a public client at:

POST https://agents.lightlead.space/mcp/oauth/register

The server returns a client_id (public client, no client secret).

Step 3 — Authenticate with OAuth 2.0 Authorization Code + PKCE

Public clients use PKCE with the S256 code challenge method.

1. Redirect the user to the authorization endpoint:

   GET https://agents.lightlead.space/mcp/oauth/authorize

   Query parameters: client_id, redirect_uri, response_type=code, scope, code_challenge, code_challenge_method=S256, state.

2. Exchange the authorization code at the token endpoint:

   POST https://agents.lightlead.space/mcp/oauth/token

   Form fields: grant_type=authorization_code, client_id, redirect_uri, code, code_verifier.

3. Refresh expired access tokens with:

   POST https://agents.lightlead.space/mcp/oauth/token

   Form fields: grant_type=refresh_token, client_id, refresh_token.

Scopes

• reports.read — read report metadata and configurations.
• reports.results — read report result rows.
• reports.refresh — trigger report refreshes.

Request only the scopes your agent actually needs.

Step 4 — Use the credential

Send the access token as a bearer token on every request:

Authorization: Bearer <access_token>

Example:

curl -H "Authorization: Bearer <access_token>" \
  https://agents.lightlead.space/mcp/...

Errors

The API returns JSON error objects with an HTTP error status code. If a token is missing, expired, or revoked, the API returns 401 Unauthorized; retry by refreshing the token or re-running the authorization flow.