API Authentication

Authenticate your Capture API requests with your API key, sent as HTTP Basic credentials.

Overview

The Capture API uses HTTP Basic authentication with an API key: the base64 encoding of client_id:client_secret. There is no token exchange — you send the key on every request.

The same credentials authenticate the FHIR API, so a single API key covers a whole integration:

• Create sessions programmatically via the Session Management API
• Import and export data through the FHIR API
• Integrate with EHR/LIS systems in the background, without user interaction

Requests are made by your backend. Never send your API key to a browser or a mobile app.

Obtain Client Credentials

Before you can authenticate, obtain client credentials from Tiro.health:

1. Contact your Tiro.health account manager or support team
2. Provide information about your integration:
   • Organization name
   • Integration purpose (e.g., EHR integration, data import)
   • Expected API usage
3. Receive your credentials:
   • client_id — your application's unique identifier
   • client_secret — your application's secret key (keep this secure!)

Important: Store your client_secret securely. Never commit it to version control or expose it in client-side code.

Authenticate a Request

Authorization: Basic base64(client_id:client_secret)

curl -X POST https://auth.tiro.health/sessions \
  -u "client_id:client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "patient/Patient.read",
    "patient": 123
  }'

End-user Identification

An API key authenticates your system, not a person. Some requests need to be attributed to a specific end-user — the practitioner filling in a report, for example.

Add the X-User-Id header to act as that user. Its value is an identifier token: the practitioner's identifier system and value joined with a pipe (|), matching an identifier on a Practitioner you created.

curl https://reports.tiro.health/fhir/r5/Patient \
  -u "client_id:client_secret" \
  -H "X-User-Id: http://myhospital.org/clinical-staff/user-ids|123"

Without the header, the request acts as the service account tied to your API key. See FHIR API Authentication for details.

Security Best Practices

Protect Your Client Credentials

• Never commit client_secret to version control (use environment variables or secret management)
• Never expose credentials in client-side code, browsers, mobile apps, or public repositories
• Use HTTPS only — always use encrypted connections when transmitting credentials
• Rotate regularly — change your credentials periodically or if compromised

API Request Security

• Server-side only — the API key is a backend credential; the end-user's browser gets a session cookie instead, via session handover
• Validate responses — check for authentication errors and handle them appropriately
• Rate limiting — implement backoff strategies for rate-limited responses
• Minimal permissions — request only the scopes your integration needs

Monitoring and Auditing

• Log access — keep audit logs of API access, but never log credentials
• Monitor usage — track API usage patterns to detect anomalies
• Alert on failures — set up alerts for repeated authentication failures
• Review regularly — periodically review client access and permissions

Next Steps

Now that you can authenticate, you can:

• Create sessions — hand an authenticated user over to Tiro.health
• Access FHIR resources — query and modify patient data via the FHIR API
• Import data — set up background data synchronization with your EHR/LIS

For user-delegated access with context launch, see SMART on FHIR.