Authentication and configuration

API key setup, authentication headers, and HTTP client configuration for the SofIA Codify API

Authorization token

All API calls require a Bearer token in the Authorization header.

Format

Authorization: Bearer YOUR_TOKEN_HERE

How to get your token?

After service contracting, you will receive:

Production token

Development token

For testing

Corresponding endpoints

Token security

Never expose your token in client-side code (browser JavaScript). Store it as an environment variable or secret, rotate it periodically, and use different tokens for development and production.

---

Optional headers (recommended)

Doctor and patient identifiers

For traceability and regulatory compliance:

x-doctor: dr_123
x-patient: pt_456

Usage:

• Access auditing
• Debugging and technical support
• GDPR/HIPAA compliance
• Usage analytics

Note: These identifiers are logged for auditing purposes but do not affect request processing.

Note

These identifiers should be sent as HTTP headers, not in the request body. The Codify API uses headers for tracking metadata to keep the request body focused on the medical content.

---

Available environments

Development

URL: Provided upon direct request

Features:

More relaxed rate limits

Do not use for real patient data

More verbose logs for debugging

No SLA guarantees

No per-request costs

Recommended usage:

Development and initial integration

JSON schema testing

Workflow validation

Automated testing

Production

URL: Provided after deployment (customized per client)

Features:

High availability (99.9% SLA)

Guaranteed processing

24/7 support

Metrics and monitoring

Recommended usage:

HIS/EHR system integration

Real data processing

Production workflows

---

HTTP client configuration

Timeouts and retries

For timeout configuration and retry strategies with exponential backoff, see Retry strategy.

Basic recommendations:

• Timeout: 600 seconds (10 minutes) for Codify API
• Retries: 3 attempts for 5xx and 429 errors
• Exponential backoff: 1s, 2s, 4s…

---

Additional headers

Content-Type

Should always be application/json:

Content-Type: application/json

User-Agent (optional)

Recommended to identify your application:

User-Agent: MyHIS/1.0 (XYZ Hospital)

---

Complete configuration example

Python

import os
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

# Configuration
API_URL = os.getenv('OMNISCRIBE_API_URL')  # Provided after contracting
API_TOKEN = os.getenv('OMNISCRIBE_API_TOKEN')

# Client with retries
session = requests.Session()
retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry)
session.mount('http://', adapter)
session.mount('https://', adapter)

# Default headers
session.headers.update({
    'Authorization': f'Bearer {API_TOKEN}',
    'Content-Type': 'application/json',
    'User-Agent': 'MyHIS/1.0'
})

# Usage
def codify(medical_note, doctor_id=None, patient_id=None, model=None):
    payload = {
        'medical_note': medical_note
    }
    
    if model:
        payload['model'] = model
    
    headers = {}
    if doctor_id:
        headers['x-doctor'] = doctor_id
    if patient_id:
        headers['x-patient'] = patient_id
    
    response = session.post(
        f'{API_URL}/v1/codify',
        json=payload,
        headers=headers,
        timeout=600  # 10-minute timeout for Codify
    )
    response.raise_for_status()
    return response.json()

# Example usage
result = codify(
    medical_note="Patient with Type 2 Diabetes...",
    doctor_id="dr_123",
    patient_id="pt_456",
    model="balanced"
)

print(f"Codes found: {len(result['final_code_assessments'])}")
for assessment in result['final_code_assessments']:
    print(f"  {assessment['code']}: {assessment['description']}")

JavaScript (Node.js)

const axios = require('axios');
const axiosRetry = require('axios-retry');

// Configuration
const API_URL = process.env.OMNISCRIBE_API_URL;  // Provided after contracting
const API_TOKEN = process.env.OMNISCRIBE_API_TOKEN;

// Client with retries
const client = axios.create({
  baseURL: API_URL,
  timeout: 600000,  // 10-minute timeout for Codify
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json',
    'User-Agent': 'MyHIS/1.0'
  }
});

axiosRetry(client, {
  retries: 3,
  retryDelay: axiosRetry.exponentialDelay,
  retryCondition: (error) => {
    return axiosRetry.isNetworkOrIdempotentRequestError(error) ||
           error.response?.status === 429 ||
           error.response?.status >= 500;
  }
});

// Usage
async function codify(medicalNote, doctorId, patientId, model) {
  const headers = {};
  if (doctorId) headers['x-doctor'] = doctorId;
  if (patientId) headers['x-patient'] = patientId;

  const payload = {
    medical_note: medicalNote
  };
  
  if (model) payload.model = model;

  const response = await client.post('/v1/codify', payload, { headers });

  return response.data;
}

// Example usage
const result = await codify(
  "Patient with Type 2 Diabetes...",
  "dr_123",
  "pt_456",
  "balanced"
);

console.log(`Codes found: ${result.final_code_assessments.length}`);
result.final_code_assessments.forEach(assessment => {
  console.log(`  ${assessment.code}: ${assessment.description}`);
});

module.exports = { codify };

---

Security and best practices

Use environment variables for tokens

Hardcode tokens in source code

Implement appropriate timeouts

Expose tokens in client (browser)

Configure automatic retries

Share tokens between environments

Always use HTTPS

Disable SSL certificate validation

Include doctor/patient identifiers for auditing

Ignore authentication errors

---

Next steps

Request/response structure

View examples

Error handling