Authentication

All Optropic API requests require an API key passed via the X-API-Key header. The SDK handles this automatically.

API Key Format

Prefix	Environment	Description
optr_live_*	Production	Real assets, real verification
optr_test_*	Sandbox	Test data, no billing

The SDK auto-detects the environment from the key prefix. No manual configuration is needed.

Permissions

API keys can be scoped with granular permissions. Use the Permission constants for type-safe key creation:

TypeScript

import { Permission } from 'optropic';

// Create a read-only key
const key = await client.keys.create({
  environment: 'live',
  label: 'Read-only integration',
  permissions: [Permission.ASSETS_READ, Permission.ASSETS_VERIFY],
});

Python

from optropic import Permission

key = client.keys.create(
    environment="live",
    label="Read-only integration",
    permissions=[Permission.ASSETS_READ, Permission.ASSETS_VERIFY],
)

Available Permissions

Permission	Description
assets:read	List and retrieve assets
assets:write	Create and update assets
assets:verify	Verify asset authenticity
audit:read	Query audit trail
compliance:read	Access compliance reports
keys:manage	Create and revoke API keys
schemas:manage	Manage vertical schemas
documents:enroll	Enroll document fingerprints
documents:verify	Verify document fingerprints
provenance:read	Read provenance chains
provenance:write	Record provenance events
webhooks:manage	Create and manage webhooks

Permission Groups

Group	Permissions Included
Permission.ALL_READ	assets:read, audit:read, compliance:read, provenance:read
Permission.ALL_WRITE	assets:write, assets:verify, documents:enroll, documents:verify, provenance:write, webhooks:manage, keys:manage, schemas:manage
Permission.all()	All permissions combined

Rate Limits

The SDK automatically parses rate limit headers after every response:

TypeScript

const rl = client.rateLimit;
if (rl) {
  console.log(`${rl.remaining}/${rl.limit} requests remaining`);
  console.log(`Resets at: ${rl.reset}`);
}

Python

rl = client.rate_limit
if rl:
    print(f"{rl.remaining}/{rl.limit} requests remaining")
    print(f"Resets at: {rl.reset}")

Request Correlation

Every request includes an X-Request-ID header for end-to-end tracing. The SDK generates UUIDs automatically. Use this ID when contacting support.

Debug Logging

Enable debug mode to log all requests and responses (API keys are automatically redacted):

TypeScript

const client = new OptropicClient({
  apiKey: 'optr_live_...',
  debug: true, // logs to console
});

Python

import logging
logging.getLogger("optropic").setLevel(logging.DEBUG)

client = Optropic(api_key="optr_live_...")