Authentication
Authenticate with an organization API key, an OAuth app grant, or a Business browser session.
For API-key-enabled operations, send an organization key in the x-api-key header. Keys start with ov_ and are created under Manage Settings → API Keys by organization admins and members with API-key access (how to create one). Other REST operations accept an authorized OAuth grant or a Business session, except browser-only flows.
Never expose keys in browser code
Anyone who has a key can read your business data. Call the Business API only from your server, a worker, or a trusted internal tool. If a browser needs the data, route the request through an authenticated endpoint on your server.
Send the key
The SDK adds the header for you. Send it yourself when you call the REST API directly.
Base URL and header
Production requests go to https://api.orvelt.com/v1; every path in these docs is relative to it. To use staging or a proxy, set ORVELT_API_BASE_URL to its URL without a trailing slash.
curl --request GET \
--url "$ORVELT_API_BASE_URL/project/PROJECT_ID/opinions" \
--header "x-api-key: $ORVELT_BUSINESS_API_KEY"A missing, mistyped, expired, or revoked key returns 401. A valid key without the operation's permission, or a project in another organization, returns 403.
What a key can do
A key belongs to one organization and works for every project in it. A request for a project in a different organization returns 403, even if you know that project's ID. Each endpoint page lists its authentication options and required grant.
Included permissions
New keys include the permissions below. Existing keys retain their stored grants; no new permissions are added automatically.
| Resource | Actions | What the key can do |
|---|---|---|
opinions | read | List opinions. |
answers | read | List answers. |
subscribers | read, invite | List and count subscribers, and send invitations. |
questions | read, create, update, delete | Manage project questions. |
link | read, create | List, create, and email delivery links. |
qr | read | Display the current rotating QR code. |
Keys also carry delivery create and analytics read, which no public Business REST operation uses. subscribers read does not grant subscribers invite.
OAuth app access
OAuth clients use the authorization-code flow with S256 PKCE through the Business OAuth endpoints under /biz-auth/oauth2. Discover the authorization server from https://api.orvelt.com/.well-known/oauth-protected-resource/v1; do not guess token endpoints.
Request the exact API resource https://api.orvelt.com/v1 and business:read. Request business:write only for changes, and offline_access only to stay connected. The approval page starts every resource at Read; the person can choose None, Read, or Write for each resource. Write requires both the requested write scope and an explicit Write choice.
Send the API access token in Authorization: Bearer ACCESS_TOKEN, never a query parameter. Do not also send x-api-key. The API verifies the token's signature, issuer, audience, expiry, live consent, resource choices, organization membership, and applicable project-team permissions. A valid token without access returns 403; an invalid, expired, or disconnected grant returns 401. Supplied credentials never fall back to a browser cookie.
The CLI calls the API directly using its own OAuth grant. Business MCP uses the same authorization policy but a separate MCP token audience. An MCP token cannot be replayed against the API, or vice versa.
This change requires a server deployment. Existing mcp:read / mcp:write grants must reconnect after deployment; they are not silently upgraded.
Session-only operations
Billing changes, OAuth connection management, and Better Auth organization/team administration remain browser-session-only. Agents cannot rename organizations or manage members through an OAuth token. Opinion replies and webhook configuration accept resource-authorized OAuth tokens, but reject API keys with 403.
Use a Business session
Organization-scoped operations use the session's active organization; project-scoped operations also check access to the requested project. Omit x-api-key entirely: a supplied key takes precedence over the session cookie, so sending both does not enable session-only operations.
The examples use ORVELT_BUSINESS_SESSION_COOKIE for an authorized cookie header, or businessSessionCookie in trusted server-side Fetch calls. Treat this cookie as a secret; do not copy it into browser JavaScript or logs. Browser requests must also pass the existing origin and CSRF checks.