API Authentication

Authenticate your API requests to Tiro.health using OAuth2 client credentials flow for secure machine-to-machine communication.

Overview

The Tiro.health Capture API uses OAuth2 client credentials flow for authentication. This is the standard approach for server-to-server communication where your application needs to access the API on behalf of itself, not a specific user.

When to Use OAuth2 Client Credentials

Use OAuth2 client credentials authentication when you need to:

• Create sessions programmatically via the Session Management API
• Access FHIR resources for data import and export
• Integrate with EHR/LIS systems in the background without user interaction
• Automate workflows that interact with Tiro.health programmatically

Key Benefits

• Secure: Client credentials are never exposed in URLs or browser contexts
• Standard: Follows OAuth2 RFC 6749 specifications
• Token-based: Access tokens can be cached and reused until expiration
• Flexible: Works with any HTTP client or programming language

Authentication Flow

The OAuth2 client credentials flow follows this sequence:

1. Obtain credentials: Get your client_id and client_secret from Tiro.health
2. Request token: Exchange credentials for an access token at the token endpoint
3. Use token: Include the access token in the Authorization header of API requests
4. Refresh when expired: Request a new token when the current one expires

Obtain Client Credentials

Before you can authenticate, you need to obtain OAuth2 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.

Request Access Token

curl -X POST https://auth.tiro.health/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use Access Token

Once you have an access token, include it in the Authorization header of your API requests using the Bearer scheme.

Authorization Header Format

Authorization: Bearer 

The token grants you access to all Tiro.health API endpoints based on your client's permissions, including:

• Session Management API - Create and manage user sessions
• FHIR API - Access patient data, questionnaires, and responses
• Task API - Create and manage tasks for users

curl https://reports.tiro.health/session \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "patient/Patient.read",
    "patient": 123
  }'

Token Expiration

Access tokens are temporary and expire after a set period (typically 1 hour).

Handling Token Expiration

When a token expires, API requests will return a 401 Unauthorized error:

{
  "error": "invalid_token",
  "error_description": "The access token expired"
}

Recommended approach:

1. Cache the token - Store the access token and its expiration time
2. Check expiration - Before making API requests, verify the token hasn't expired
3. Request new token - When expired, request a new token using your client credentials
4. Retry request - Retry the failed API request with the new token

Example: Token Management

public class TokenManager
{
    private string _accessToken;
    private DateTime _expiresAt;
    private readonly HttpClient _client = new HttpClient();

    public async Task<string> GetValidTokenAsync()
    {
        if (DateTime.UtcNow >= _expiresAt)
        {
            await RefreshTokenAsync();
        }
        return _accessToken;
    }

    private async Task RefreshTokenAsync()
    {
        var content = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("grant_type", "client_credentials"),
            new KeyValuePair<string, string>("client_id", "your_client_id"),
            new KeyValuePair<string, string>("client_secret", "your_client_secret")
        });

        var response = await _client.PostAsync(
            "https://auth.tiro.health/oauth/token",
            content
        );

        var tokenData = await response.Content.ReadFromJsonAsync<TokenResponse>();
        _accessToken = tokenData.AccessToken;
        _expiresAt = DateTime.UtcNow.AddSeconds(tokenData.ExpiresIn - 60); // 60s buffer
    }
}

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 or public repositories
• Use HTTPS only - Always use encrypted connections when transmitting credentials
• Rotate regularly - Change your credentials periodically or if compromised

Secure Token Storage

• Server-side only - Never send access tokens to client browsers or mobile apps
• Memory storage - Store tokens in memory rather than persistent storage when possible
• Encrypt at rest - If you must persist tokens, encrypt them
• Clear on logout - Dispose of tokens properly when no longer needed

API Request Security

• HTTPS only - All API requests must use HTTPS
• Validate responses - Check for authentication errors and handle them appropriately
• Rate limiting - Implement backoff strategies for rate-limited responses
• Minimal permissions - Request only the access your application needs

Monitoring and Auditing

• Log access - Keep audit logs of API access (but never log tokens or 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 understand OAuth2 authentication, you can:

• Create sessions - Use the Session Management API to create authenticated user sessions
• Access FHIR resources - Query and modify patient data via the FHIR API
• Import data - Set up background data synchronization with your EHR/LIS

For alternative authentication methods, see:

• FHIR API Authentication - Basic authentication and user identification
• SMART on FHIR - User-delegated access with context launch