Session Management API

The Session Management API allows Capture API customers to programmatically create and manage user sessions with fine-grained access control through scopes.

Overview

The Session Management API is designed for EHR and LIS systems that integrate with Tiro.health using the Capture API. It enables you to:

• Create sessions programmatically with specific scopes and FHIR context
• Control access to resources throughout the session lifetime using scope-based permissions
• Handover sessions to end-users in a browser environment
• Terminate sessions when the user logs out or the session expires

This API is particularly useful when you need to:

• Launch Tiro.health forms with pre-configured patient and encounter context
• Restrict what data users can access during a session
• Integrate Tiro.health into your application's authentication flow
• Provide seamless user experience with session continuity

Base URL

The Session Management API is served by the Tiro.health Auth Service:

https://auth.tiro.health

Authentication

POST /sessions, GET /sessions/{id} and DELETE /sessions/{id} authenticate with your API key over HTTP Basic — the base64 encoding of client_id:client_secret. The two handover endpoints are unauthenticated by design: they are opened by the end-user's browser and carry a single-use token instead.

The API key must belong to a data tenant, otherwise session creation fails with 403.

Session Lifecycle

A typical session follows this lifecycle:

1. Session Creation: Your backend calls POST /sessions, optionally including scopes, FHIR context (Patient, Encounter) and a post_submit_redirect. The session is created inactive and comes back with a single-use handover_token
2. Browser Handover: The end-user's browser is sent to /sessions/$handover with that token and a next Launch URL. The session is activated, a secure cookie is set in the browser, and the user lands on the task
3. Completing the Report: The user fills in and submits the report, with access controlled by the session's scopes
4. Return to Your System: On submit, Tiro.health sends the browser back to your post_submit_redirect, with the resulting QuestionnaireResponse appended as a query parameter
5. Session Termination: Your backend deletes the session via DELETE /sessions/{id} (equivalent to logout), or it expires automatically

The session only becomes usable at step 2 — the handover is what activates it and binds it to the end-user's browser. Your backend never holds the session cookie.

Create a Session

curl -X POST https://auth.tiro.health/sessions \
  -u "<client_id>:<client_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "patient/Patient.read patient/QuestionnaireResponse.write",
    "patient": 123,
    "deployment_mode": "embedded",
    "post_submit_redirect": "https://ehr.example.com/reports/done"
  }'

{
  "id": 789,
  "handover_token": "hDk3n...T9wQ",
  "active": false,
  "patient": { "reference": "Patient/123" },
  "encounter": null,
  "deployment_mode": "embedded",
  "post_submit_redirect": "https://ehr.example.com/reports/done",
  "expired_timestamp": "2026-07-14T18:00:00Z"
}

Session Handover

https://auth.tiro.health/sessions/$handover
  ?token=<handover_token>
  &next=https%3A%2F%2Fapp.tiro.health%2Fexternal%2Fv1%3Ftask%3DTask%2F123

// Redirects to the 'next' URL with session cookie set
Location: https://app.tiro.health/external/v1?task=Task/123
Set-Cookie: auth_session=<session_id>; HttpOnly; Secure; SameSite=Strict

Launch URL

https://app.tiro.health/external/v1?task=Task/123

Get Session Information

curl https://auth.tiro.health/sessions/789 \
  -u "<client_id>:<client_secret>"

{
  "id": 12345,
  "user": {
    "id": 67890,
    "email": "doctor@hospital.org",
    "name": "Dr. Smith"
  },
  "data_tenant": {
    "id": 1,
    "name": "Hospital Name"
  },
  "active": true,
  "expired_timestamp": "2025-11-20T18:00:00Z",
  "created_timestamp": "2025-11-20T10:00:00Z",
  "last_modified_timestamp": "2025-11-20T10:00:00Z",
  "deployment_mode": "embedded",
  "fhir_server": {
    "address": "https://fhir.hospital.org/R4",
    "scope": ["patient/Patient.read", "patient/QuestionnaireResponse.write"]
  }
}

Delete a Session

curl -X DELETE https://auth.tiro.health/sessions/789 \
  -u "<client_id>:<client_secret>"

// Empty response body

Scope-based Access Control

Scopes define what actions and resources a user can access during their session. When you create a session with specific scopes, those restrictions are enforced throughout the entire session lifetime.

Scope Format

Scopes follow the FHIR SMART on FHIR format: <context>/<resourceType>.<action>

Supported formats:

• patient/<resourceType>.<action> - Patient-scoped access to specific resource types
• system/<resourceType>.<action> - System-wide access to specific resource types

Examples:

• patient/QuestionnaireResponse.write - Write access to reports (QuestionnaireResponses) in the patient's compartment
• patient/QuestionnaireResponse.read - Read access to reports in the patient's compartment
• patient/Patient.read - Read access to patient resources in the patient's compartment
• patient/Encounter.read - Read access to encounters in the patient's compartment
• system/QuestionnaireResponse.read - System-wide read access to all reports
• patient/Patient.read patient/QuestionnaireResponse.write - Multiple scopes can be combined

Reports authored in Tiro.health are stored as FHIR QuestionnaireResponse resources, so QuestionnaireResponse is the resource type you scope to control read and write access to captured data. Patient, Encounter, and Practitioner are the supporting context resources and are granted read-only.

How Scopes Work

When a session is created with scopes:

1. The scopes are stored with the session
2. All FHIR API requests during the session are checked against these scopes
3. Requests for resources or actions not covered by the scopes are denied
4. Scopes remain active until the session is deleted or expires

Example: Restricted Session

# Create a read-only session for patient data
curl -X POST https://auth.tiro.health/sessions \
  -u "<client_id>:<client_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "patient/Patient.read patient/Encounter.read patient/QuestionnaireResponse.read",
    "patient": 123
  }'

In this session, the user can read patient, encounter, and report data but cannot modify anything. Any attempt to create or update resources will be denied.

FHIR Context

Sessions can include FHIR context to associate them with specific patients and encounters. There are two ways to specify context:

Using Direct IDs

When you have the internal FHIR server IDs, use the direct patient and encounter parameters:

{
  "patient": 123,
  "encounter": 456
}

This is the simplest approach when your system already uses Tiro.health's FHIR server IDs.

Using External Identifiers with fhirContext

When integrating with external systems that use their own identifier namespaces, use the fhirContext array following the SMART on FHIR launch context specification:

{
  "fhirContext": [
    {
      "identifier": {
        "system": "http://hospital.org/patient-ids",
        "value": "P-12345"
      },
      "type": "Patient",
      "role": "launch"
    },
    {
      "identifier": {
        "system": "http://hospital.org/encounter-ids",
        "value": "E-67890"
      },
      "type": "Encounter",
      "role": "launch"
    }
  ]
}

Key features:

• identifier: Specifies the external system identifier (system + value)
• type: Resource type (Patient or Encounter)
• role: "launch": Indicates this is the primary launch context for the session

Identifier Resolution

When using external identifiers, Tiro.health will:

1. Look up existing resources with matching identifiers
2. Create new resources if no match is found
3. Associate the session with the resolved or created resources

This enables seamless cross-system integration without requiring ID mapping or pre-registration of resources.

Migrating from /session

The singular /session endpoints are deprecated. They still work, but new integrations should use /sessions, and existing ones should move over.

Authentication does not change. You keep authenticating with your API key over HTTP Basic, exactly as before.

Two things change beyond the path:

The handover token is returned in the response body. POST /sessions responds 201 with handover_token in the JSON. You no longer read it off a cookie.

Deleting a session needs its id. DELETE /sessions/{id} is called by your backend with your API key, rather than by the browser with a cookie. Keep the id from the create response.

Security Considerations

Token Expiration

• Session tokens expire after 5 minutes and are single-use only
• Active sessions have configurable expiration times
• Expired tokens cannot be used for handover and will return a 401 error

Token Security

• Session tokens should be treated as sensitive credentials
• Tokens are deleted immediately after successful handover (one-time use)
• Always use HTTPS when transmitting tokens
• Never log or store session tokens

Cookie Security

Session cookies are configured with security best practices:

• HttpOnly - Cannot be accessed via JavaScript
• Secure - Only transmitted over HTTPS
• SameSite=Strict - Protection against CSRF attacks
• Scoped to tiro.health domain

Best Practices

1. Minimize scope - Only grant the minimum permissions needed
2. Short-lived tokens - Use the default 5-minute token expiration
3. Secure token transmission - Pass tokens via secure form POST, not URL parameters
4. Immediate handover - Complete the handover flow as quickly as possible
5. Explicit logout - Always delete sessions when users log out
6. Monitor sessions - Track active sessions and their expiration times