See the product in action. ― Book a free demo →
All guides
Browse all guides
Documentation
Developer tools

Understand API authentication and access

Learn how the HTTP API, CLI, and MCP share OAuth authentication, site permissions, and plan requirements.

Neopress has an HTTP API under https://app.neopress.ai/api/v1. The CLI and MCP use this API to manage site resources. It is the first-party automation interface behind those tools, with OAuth authentication and site-level authorization.

For a new integration, start with the published CLI or MCP package. Neopress does not provide a public third-party API-key issuance flow. The SDK used inside these tools is bundled internally and is not a separately published package to install.

How authentication works

The CLI uses browser login and stores a renewable session locally. Remote MCP starts an OAuth connection in your AI tool and asks you to sign in and approve access. Authenticated HTTP requests use an OAuth access token in the Authorization header:

Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN

An access token represents the signed-in account. It is not a permanent API key. The CLI can also receive a valid OAuth token through NEOPRESS_ACCESS_TOKEN; a token supplied this way takes precedence over the saved session and must be kept current by the environment supplying it.

Do not put access tokens in page TSX, public browser code, repository files, or published examples. Generated Neopress pages receive supported data and form clients through the page runtime rather than authenticating to the management API.

Three checks determine access

  1. Account and membership: the session must be valid and the account must have active access to the target site.

  2. Site permissions: page and layout edits require build access; CMS entry edits require content access; analytics requires insights access. Publishing has its own permission, and site publication through the API additionally requires an owner or admin account.

  3. Site plan: external developer access starts at Launch. Growth also includes it, and an active trial provides Launch access. An Archive site without an active entitlement cannot use this surface, including ordinary site reads.

A higher plan does not add a team permission that your account lacks. Feature-specific requirements also remain in effect: adding another site language and using saved analytics events or funnels require Growth access.

OAuth scopes and site permissions are different

Use the OAuth flow supplied by your MCP client. Do not invent custom scope strings such as pages:write in the connection settings. Neopress checks the account's current site permissions for each operation. An INSUFFICIENT_SCOPE response means that the site role or assigned work permissions do not permit the requested action; it is not an instruction to generate a more powerful API key.

Recognize the HTTP contract

The following read-only example illustrates the request shape for an environment that already supplies a valid OAuth access token. Replace the example site ID with your own:

curl 'https://app.neopress.ai/api/v1/sites/123/pages' --header "Authorization: Bearer $NEOPRESS_ACCESS_TOKEN"

Successful API responses contain data, with pagination on paginated lists. Errors contain an error object with a code, message, and status. The CLI may unwrap this response for easier use, so its output is not always identical to raw HTTP output.

Rate limits vary by operation. Check X-RateLimit-Limit and X-RateLimit-Remaining when provided, and slow down after a 429 RATE_LIMITED response. Treat a saved draft, successful compile, and successful publish as distinct results when building automation.

Related guides