Developers

Authentication

The Orvine API uses bearer tokens. Every request is scoped, audited, and bound to a tenant.

Bearer tokens

request

curl https://api.orvine.app/v1/sessions \
  -H "Authorization: Bearer mk_live_01HZX..." \
  -H "Content-Type: application/json"

Keys are prefixed by environment:

mk_live_ — production tenants.
mk_test_ — sandbox tenants. Identical surface, real data isolation.
mk_int_ — partner-issued integration keys.

Key types

See the API keys admin guide for full coverage. In short:

Workspace keys — service principal of a workspace.
User keys — bound to a user; capped at their role.
Integration keys — issued to a registered partner connector.

Scopes

A request that lacks the necessary scope returns 403 permission_denied with the missing scope named in detail.

error

{
  "type": "https://errors.orvine.app/permission_denied",
  "title": "Permission denied",
  "status": 403,
  "detail": "API key is missing the 'graph:write' scope.",
  "instance": "req_01HZX..."
}

SDKs

Official SDKs handle key rotation, retries, and signed-webhook verification:

install

npm install @orvine/sdk
# or
pip install orvine
# or
go get github.com/orvine/orvine-go

typescript

import { Orvine } from "@orvine/sdk";

const orvine = new Orvine({ apiKey: process.env.ORVINE_API_KEY! });

const answer = await orvine.chat.ask({
  question: "How do we close month-end revenue?",
});
console.log(answer.citations);

Never expose live keys to the browser

The Orvine API expects calls from server-side environments. For end-user interfaces, exchange your server-issued bearer for a short-lived session token via POST /v1/auth/session-token and use that in the browser.