# auth.md

This document describes authentication for Lightsage's agent-facing interfaces. Use revocable credentials associated with a Lightsage workspace. Never embed production secrets in source code, prompts, logs, screenshots, or public artifacts.

## Interfaces

| Interface | Endpoint | Authentication |
|---|---|---|
| Public API | https://api.lightsage.com | Workspace API key |
| MCP server | https://mcp.lightsage.com/mcp | OAuth 2.1 or workspace API key |

The public API is version 2: its paths start with `/v2` and its OpenAPI document is https://api.lightsage.com/v2/openapi.json. Use these paths rather than the earlier `/v1` ones.

The public API accepts `X-Lightsage-Api-Key`. It does not accept browser session cookies or OAuth bearer tokens directly. The MCP server accepts OAuth bearer tokens and exchanges the authenticated identity for a scoped, revocable Lightsage API key. It also accepts a caller-supplied workspace API key.

## OAuth registration for MCP agents

The MCP server publishes Protected Resource Metadata at https://mcp.lightsage.com/.well-known/oauth-protected-resource/mcp.

The authorization server is https://clerk.usesapient.com. It supports authorization code with PKCE and refresh tokens.

- Authorization endpoint: https://clerk.usesapient.com/oauth/authorize
- Token endpoint: https://clerk.usesapient.com/oauth/token
- Dynamic client registration: https://clerk.usesapient.com/oauth/register
- Token revocation: https://clerk.usesapient.com/oauth/token/revoke
- JWKS: https://clerk.usesapient.com/.well-known/jwks.json

Request only the scopes required by the client. The MCP authorization flow currently advertises `openid`, `profile`, `email`, and `offline_access`. A human user signs in and selects the Lightsage organization the client may access.

## Workspace API keys

A human user can create a revocable key in Lightsage:

1. Sign in at https://app.lightsage.com.
2. Open https://app.lightsage.com/{orgId}/settings/api-keys for the intended workspace.
3. Create a key for the agent or sandbox and store the returned value securely. Plaintext is shown once.
4. Send the key as `X-Lightsage-Api-Key` to the public API or MCP server.

Use a dedicated test workspace or sandbox key for automation and revoke it after testing. Lightsage does not publish shared test credentials or production secrets.

## Agent accounts with AgentID

An AI agent that has an AgentID can sign in to Lightsage with its own identity instead of a human user's credentials. Open https://app.usesapient.com/welcome/agentid to start the sign-in. It redirects to AgentID (https://auth.agentid.com), an OpenID Connect provider, and returns to Lightsage when the agent approves. Sign-in requests the `openid`, `email`, and `profile` scopes.

Every agent starts in a limited workspace of its own:

- a small starting credit balance
- one low-cost model per coding agent; a request for any other model is rejected with the name of the model to use
- at most two eval or prompt runs at a time; further runs wait in the queue
- no dashboard: the workspace is used through the API, CLI, and MCP server

Signing in gives the agent an API key for the public API, CLI, and MCP server. The page the browser lands on shows it; send it as `X-Lightsage-Api-Key`. The key stays the same on every sign-in, and the signed-in session can read it again at any time:

```
GET https://app.usesapient.com/api/proxy/api/v1/onboarding/agent/api-key
```

A new workspace has no company yet. Set it up with one request, using the signed-in session:

```
POST https://app.usesapient.com/api/proxy/api/v1/onboarding/agent/setup
{"domain": "example.com", "description": "optional", "docs_url": "optional", "competitor_domains": ["optional.com"]}
```

Only `domain` is required. After sign-in the browser lands on a form that sends this request for you. The request returns `202` and a background job researches competitors and creates topics, prompts, and evals. While the workspace is limited, nothing is run automatically: start runs yourself.

The response also carries the same `api_key`.

To lift those limits, open https://app.usesapient.com/welcome/agentid/verify while signed in. It sends the agent back to AgentID with the `owner_profile` and `owner_email` scopes; if the agent is not permitted to share its owner, AgentID holds the request until the owner approves it. Lightsage then applies the same rules as a person signing up to the owner's verified email:

- A company email gives the workspace the standard trial, or adds the agent to the workspace that owner already has.
- A personal email address does not qualify. The workspace stays limited.
- Some organizations are on a waitlist and stay limited. Contact team@lightsage.com for access.

Default workspace API-key scopes are:

- `read`
- `write`
- `jobs:read`
- `jobs:run`
- `jobs:cancel`

## Failure recovery

- `401`: authenticate again, replace an invalid or expired token, or create a new API key if the old key was revoked.
- `403`: request a credential with the required workspace scope.
- `409`: complete organization selection or resolve the reported resource conflict.
- `429`: honor retry guidance and reduce request frequency.
- OAuth issuer or audience error: refetch Protected Resource Metadata and authorization-server metadata, then ensure the token audience is https://mcp.lightsage.com/mcp and the issuer is https://clerk.usesapient.com.
- Lost API key: revoke it in workspace settings and create a replacement. Lightsage cannot reveal the plaintext value again.

## Discovery and documentation

- API catalog: https://lightsage.com/.well-known/api-catalog
- OpenAPI: https://api.lightsage.com/v2/openapi.json
- API documentation: https://lightsage.com/docs/api-reference/introduction
- MCP Server Card: https://lightsage.com/.well-known/mcp/server-card.json
- Agent Skills: https://lightsage.com/.well-known/agent-skills/index.json
- General documentation: https://lightsage.com/docs