Authentication

SDK ยืนยันตัวตนทุก request โดยใช้ API key ของคุณ หน้านี้อธิบายวิธีการตั้งค่า ความแตกต่างระหว่างประเภท token และวิธีรักษาความปลอดภัยของ credential

การตั้งค่า API Key

ส่ง API key ให้ OcrivaClient ตอนที่สร้าง instance:

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

SDK ส่ง key ผ่าน header X-API-Key ใน request ทุกครั้ง คุณไม่ต้องจัดการ header เอง

Custom Base URL

สำหรับ deployment แบบ self-hosted หรือ environment การพัฒนา ให้ override baseUrl:

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

URL ต้องมี scheme (https:// หรือ http://) หาก URL ไม่ถูกต้อง constructor จะ throw OcrivaError ก่อนที่จะมีการส่ง request ใด ๆ

ประเภท Token

Ocriva ออก API token 2 ประเภท ประเภท token ที่คุณใช้จะกำหนดว่า SDK สามารถเข้าถึง resource ใดได้บ้าง และจำเป็นต้องส่ง projectId ในแต่ละ call หรือไม่

ตัวอย่าง Organization Token

เมื่อใช้ organization token ให้ส่ง projectId ทุกครั้งที่จำเป็น:

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

เมื่อใช้ project token project จะถูกกำหนดโดย 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

อย่า hardcode API key ไว้ในไฟล์ source code เก็บไว้ใน environment variable และโหลดขณะ runtime:

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

สำหรับการพัฒนาในเครื่อง ใช้ไฟล์ .env (และเพิ่มเข้า .gitignore):

# .env
OCRIVA_API_KEY=ocr_live_...

จากนั้นโหลดก่อนที่แอปพลิเคชันจะเริ่มต้น:

# 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!,
});

แนวทางปฏิบัติด้านความปลอดภัย

• อย่า commit API key ลง version control ใช้ .gitignore เพื่อ exclude ไฟล์ .env
• ใช้ environment variable ใน production แพลตฟอร์ม hosting ส่วนใหญ่ (Vercel, Railway, Fly.io) มี UI สำหรับจัดการ secret
• ใช้ Doppler หรือ secrets manager สำหรับ environment ของทีม เพื่อแชร์ secret อย่างปลอดภัยโดยไม่เปิดเผยเป็น plain text
• หมุนเวียน key เป็นประจำ ลบ token ที่ถูก compromise ทันทีใน Ocriva Dashboard ที่ Settings → API Tokens
• เลือกใช้ project token แทน organization token เมื่อ integration ของคุณต้องการเข้าถึงเพียง project เดียว — ช่วยจำกัดความเสียหายหาก key ถูกเปิดเผย
• อย่า log API key หลีกเลี่ยงการแสดง config.apiKey หรือ request header ดิบใน application log