Authentication

The SDK authenticates every request using your API key. This page explains how to configure it, the difference between token types, and how to keep your credentials secure.

API Key Setup

Pass your API key to OcrivaClient when you create the instance:

import { OcrivaClient } from '@ocriva/sdk';
 
const client = new OcrivaClient({
  apiKey: 'ocr_live_...',
});

The SDK sends the key as an X-API-Key header on every request. You do not need to manage headers manually.

Custom Base URL

For self-hosted deployments or development environments, override baseUrl:

const client = new OcrivaClient({
  apiKey: process.env.OCRIVA_API_KEY!,
  baseUrl: 'https://api.your-domain.com/v1',
});

The URL must include a scheme (https:// or http://). An invalid URL causes the constructor to throw an OcrivaError before any requests are made.

Token Types

Ocriva issues two kinds of API tokens. The token type you use determines which resources the SDK can access and whether you need to pass a projectId on each call.

Organization Token Example

With an organization token, always pass projectId when required:

const client = new OcrivaClient({
  apiKey: process.env.OCRIVA_ORG_TOKEN!,
});
 
// projectId is required when using an organization token
const history = await client.processingHistory.list({
  projectId: 'proj_abc123',
  status: 'completed',
});

Project Token Example

With a project token, the project is already implied by the token:

const client = new OcrivaClient({
  apiKey: process.env.OCRIVA_PROJECT_TOKEN!,
});
 
// projectId is optional — the token already scopes to one project
const history = await client.processingHistory.list({
  status: 'completed',
});

Environment Variables

Never hardcode API keys in source files. Store them in environment variables and load them at runtime:

import { OcrivaClient } from '@ocriva/sdk';
 
const client = new OcrivaClient({
  apiKey: process.env.OCRIVA_API_KEY!,
});

For local development, use a .env file (and add it to .gitignore):

# .env
OCRIVA_API_KEY=ocr_live_...

Then load it before your application starts:

# Node.js 20.6+ (built-in)
node --env-file=.env dist/index.js
 
# Or use dotenv
npm install dotenv

import 'dotenv/config';
import { OcrivaClient } from '@ocriva/sdk';
 
const client = new OcrivaClient({
  apiKey: process.env.OCRIVA_API_KEY!,
});

Security Best Practices

• Never commit API keys to version control. Use .gitignore to exclude .env files.
• Use environment variables in production. Most hosting platforms (Vercel, Railway, Fly.io) provide a secrets UI.
• Use Doppler or a secrets manager for team environments to share secrets securely without exposing them in plain text.
• Rotate keys regularly. Delete compromised tokens immediately in the Ocriva Dashboard under Settings → API Tokens.
• Prefer project tokens over organization tokens when your integration only needs access to a single project — this limits the blast radius if a key is leaked.
• Do not log API keys. Avoid printing config.apiKey or raw request headers in application logs.