# Authentication

URL: /docs/developers/authentication

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](/docs/developers/api-keys)). 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 [#send-the-key]

The SDK adds the header for you. Send it yourself when you call the REST API directly.

### Base URL and header [#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.

```bash
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 [#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](/docs/api-reference) lists its authentication options and required grant.

### Included permissions [#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-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](/docs/ai) 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 [#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 [#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.