> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```http theme={null}
Authorization: Bearer YOUR_TOKEN_HERE
```
### How to get your token?
After service contracting, you will receive:
For testing
### 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:
```http theme={null}
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:**
**Recommended usage:**
### Production
**URL:** Provided after deployment (customized per client)
**Features:**
**Recommended usage:**
***
## HTTP client configuration
### Timeouts and retries
For timeout configuration and retry strategies with exponential backoff, see [Retry strategy](/sofia/en/api/operations#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`:
```http theme={null}
Content-Type: application/json
```
### User-Agent (optional)
Recommended to identify your application:
```http theme={null}
User-Agent: MyHIS/1.0 (XYZ Hospital)
```
***
## Complete configuration example
### Python
```python theme={null}
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)
```javascript theme={null}
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
***
## Next steps