API Endpoint Configuration
Configure secure external API endpoints for workflow data transmission
Overview
API endpoint configurations define how Safe AI Workbench transmits data to external systems. Each endpoint includes authentication credentials, security settings, retry policies, and custom headers.
Common Use Cases:
- FHIR server data submission
- Insurance claim API integration
- EHR system data sync
- Third-party analytics platforms
- Custom webhook endpoints
Accessing Endpoint Configuration
API endpoint configuration is available in the System Admin area (site admin access required).
Navigate to System Settings
Click on your profile menu → System Admin
Go to API Endpoints
In the left sidebar, navigate to API Endpoints
Create or Edit Endpoint
Click + New Endpoint or edit an existing configuration
🔒 Admin Only: API endpoint configuration requires site admin permissions. Contact your organization administrator if you don't have access.
Basic Information
Endpoint Name
Descriptive name for the endpoint (e.g., "Production FHIR Server", "Claims Processing API")
Description
Optional notes about the endpoint's purpose and usage
URL
Complete API endpoint URL (must use HTTPS for security)
https://fhir.example.com/api/v1/data
HTTP Method
Request method: POST, PUT, or PATCH
Most workflows use POST for creating new resources
Authentication
Choose the authentication method required by the external API:
Bearer Token
Most common for REST APIs. Token sent in Authorization header.
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Token stored securely in Azure Key Vault
API Key
Simple API key sent in custom header (e.g., X-API-Key).
X-API-Key: sk-abc123xyz456
Specify header name and key value
OAuth 2.0
Client credentials flow for service-to-service authentication.
Requires: Token URL, Client ID, Client Secret, optional scope
mTLS Certificate
Mutual TLS for highest security (certificate-based authentication).
Certificate stored in Azure Key Vault, automatically presented during TLS handshake
🔐 Credential Security: All credentials (tokens, keys, certificates) are stored in Azure Key Vault, not in the database. Only encrypted references are stored.
Security & TLS Settings
TLS Version
Minimum TLS version: 1.2 or 1.3 (recommended)
TLS 1.0 and 1.1 disabled for security compliance
Certificate Pinning (Optional)
Enable to validate server certificate thumbprint for additional security.
Prevents man-in-the-middle attacks by validating expected certificate
Certificate Thumbprint
SHA-256 thumbprint of the expected server certificate (if pinning enabled).
A1B2C3D4E5F6...
📖 TLS 1.3 Benefits: Better performance, stronger encryption, and reduced handshake latency compared to TLS 1.2. Use when supported by target API.
Retry & Response Handling
Configure automatic retry behavior for transient failures:
Max Retries
Number of retry attempts (0-10). Recommended: 3
Retries triggered on network errors or 5xx server errors
Initial Retry Delay
Delay before first retry in seconds. Recommended: 1-2 seconds
Backoff Multiplier
Exponential backoff multiplier. Recommended: 2.0
Delays: 1s → 2s → 4s → 8s (doubles each retry)
Expected Status Codes
Comma-separated list of success status codes. Default: 200,201,202,204
Other codes treated as errors and trigger retries
Require Acknowledgment
Expect response body with acknowledgment field (optional for some APIs).
Retry Logic Example:
Attempt 1: POST request → 503 Service Unavailable
Wait 1 second...
Attempt 2: POST request → Network timeout
Wait 2 seconds...
Attempt 3: POST request → 200 OK ✓
Transmission successful!Custom Headers
Add custom HTTP headers required by the target API (JSON format):
{
"X-Tenant-ID": "org-abc123",
"X-Source-System": "SafeAIWorkbench",
"X-Request-ID": "{{workflow_execution_id}}",
"Content-Type": "application/fhir+json"
}Supported Variables:
{{workflow_execution_id}} - Unique workflow execution ID
{{timestamp}} - Current timestamp (ISO 8601)
{{org_id}} - Organization ID
⚠️ Note: Don't include authentication headers here - use the Authentication section instead. Custom headers are for additional metadata only.
Testing Endpoints
Test endpoint connectivity before using in production workflows:
Save Endpoint Configuration
Complete all required fields and click Save
Click "Test Connection"
Sends test payload to verify configuration
Review Test Results
Status code, latency, and any error messages displayed
Test Result Examples:
Transmission Audit Logs
Every API transmission is logged for audit and compliance purposes:
Transmission ID
Unique identifier for each API call
Timestamp & Latency
Exact time and response time in milliseconds
Status Code & Response
HTTP status and response body (truncated)
Payload Hash
SHA-256 hash of transmitted data for integrity verification
Retry Count
Number of retry attempts before success/failure
Workflow Execution Link
Reference to parent workflow for full audit trail
📊 View Logs: Access transmission history from the endpoint detail page to monitor usage and troubleshoot issues.
Best Practices
Use descriptive endpoint names
Include environment (prod/staging) and purpose for clarity
Test thoroughly before production use
Validate with dry run mode in workflows first
Enable retries for unreliable networks
3 retries with 2x backoff handles most transient failures
Use TLS 1.3 when supported
Better security and performance than TLS 1.2
Rotate credentials regularly
Update bearer tokens and API keys per security policy
Monitor transmission logs
Review for patterns in failures or performance degradation