Skip to content

Latest commit

 

History

History
37 lines (29 loc) · 2.83 KB

request-audit-headers.md

File metadata and controls

37 lines (29 loc) · 2.83 KB
Raw

BFD Audit Headers

This document details the HTTP headers that should be included when calling BFD, to ensure that proper audit information is available to the BFD team. Future versions of BFD may enforce/require some or all of these headers.

These fields allow engineers & operators to read the BFD logs and see exactly why data was requested. Some of this information is redundant with information already captured elsewhere, but experience has shown it to be very helpful when investigating issues.

Synchronous Requests

For synchronous (i.e. non-bulk) requests, BFD users SHALL include meaningful values for as many as possible of the following HTTP headers.

  • BlueButton-OriginalQueryId: a unique ID (e.g. UUID) generated by the frontend system, per HTTP request to that frontend system.
    • This ID SHALL be included in all log events for the frontend system.
    • This allows requests to be traced across systems.
  • BlueButton-OriginalQueryCounter: start at 1 and increment for every request to BFD with the same BlueButton-OriginalQueryId value.
  • BlueButton-OriginalQueryTimestamp: an ISO-8601 UTC timestamp representing (roughly) when the original request reached the frontend system.
  • BlueButton-DeveloperId: the unique ID in the frontend system for the developer/vendor of the third-party application.
  • BlueButton-Developer: the human-readable name in the frontend system for the developer/vendor of the third-party application.
  • BlueButton-ApplicationId: the unique ID in the frontend system for the application/client that will receieve the data.
  • BlueButton-Application: the human-readable name in the frontend system for the application/client that will receive the data.
  • BlueButton-UserId: the unique ID in the frontend system for the user (e.g. beneficiary) that data is being requested on behalf of.
  • BlueButton-User: the human-readable login ID (e.g. email address) in the frontend system for the user (e.g. beneficiary) that the data is being requested on behalf of.
  • BlueButton-BeneficiaryId: the unique beneificary ID (e.g. Patient.id) from BFD for the user the beneficiary whose data is being requested.
  • x-forwarded-for: a standard header for identifying the originating IP address of a client connecting to a web server through an HTTP proxy or a load balancer.

Asynchronous Requests

For asynchronous (i.e. bulk) requests, BFD users SHALL include meaningful values for as many as possible of the following HTTP headers.

  • BlueButton-OriginalQueryId: (see above; same thing)
    • For asynchronous jobs, users SHALL use the BlueButton-OriginalQueryId for the HTTP request that created/submitted/whatever the job.
  • BULK-CLIENTID: a unique identifier of the bulk client for whom this request is for (i.e. UUID, ACO ID, NPI, Part D Contract)
  • BULK-JOBID: a unique identifier for the job (Job ID, UUID, etc.)