Authentication

How API keys work, validation expectations, and secure handling practices.

Every request to the Sellm API must include a valid API key. Sellm has two key scopes:

• Project API keys are created from a project's API Keys page and are tied to that configured brand. Use them for project data, configured prompts, project settings, and project-scoped analysis runs.
• Organization API keys are created from Organization API Integrations. Use them for brand-per-call async analysis, where the request supplies a brandName and spends prepaid API credits.

Sending your key

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer sellm_your_api_key_here

This header must be present on every request. Requests without a valid key receive a 401 Unauthorized response.

Key format

Sellm API keys follow a consistent format:

• Keys always start with the sellm_ prefix.
• The remainder is a cryptographically generated token.
• There are no separate sandbox or test keys. All keys authenticate against the production API.

If you are building client-side validation, check that the value is non-empty, starts with sellm_, and does not contain leading or trailing whitespace.

Choosing a key scope

Use a project API key when your integration is working with one existing Sellm project:

• GET /project
• GET /prompts
• POST /analysis/trigger
• GET /analysis/runs/{runId}
• POST /async-analysis without brandName

Use an organization API key when your integration needs one-off analysis without creating projects:

• POST /async-analysis with brandName
• prompt or prompts supplied in the request body
• prepaid API credits available on the organization

Organization keys cannot read or mutate project-scoped resources such as /project, /prompts, or /settings. Project keys cannot override the brand name per call.

Security best practices

• Rotate keys periodically. You can create a new key and revoke the old one from the dashboard at any time.
• Use one key per integration. If you have multiple systems accessing the API, create a separate key for each. This makes it easy to revoke access for a single integration without affecting others.
• Monitor key usage. If you suspect a key has been compromised, revoke it immediately from the dashboard and create a replacement.

Verifying your key

The simplest way to confirm that a project key is valid is to call the project endpoint:

GET /project

A 200 response with your project details means the key is active and correctly configured. This is a lightweight read-only call that is safe to use as a health check.

For organization keys, submit a small async analysis request with a brandName. The request reserves credits using this formula:

credits = prompts × providers × locations × replicates

Common authentication errors

If you receive a 401, verify that your Authorization header is formatted correctly and that the key has not been revoked in the dashboard. For 403 errors, check your current plan limits in the dashboard settings.