Merge branch 'main' into dependabot/bundler/bundler-4415e84133

CMSgov · Dec 23, 2024 · a9f0c16 · a9f0c16
2 parents b0012c0 + a5e9153
commit a9f0c16
Show file tree

Hide file tree

Showing 19 changed files with 123 additions and 92 deletions.
diff --git a/_includes/build/access_token.html b/_includes/build/access_token.html
@@ -32,19 +32,13 @@ <h4>
 <h4>
 	Access Token cURL Command
 </h4>
-	<p>
-		cURL Option 1: This cURL command requires separate Base64 encoding. We have concatenated the Base64 encoding of the ‘Client ID : Secret’ as the argument to the -H flag. Please note that the URL in the Production environment will be different. 
-	</p>
-<pre><code>curl -d "" -X POST "https://sandbox.bcda.cms.gov/auth/token" \
-	-H "accept: application/json" \
-	-H "authorization: Basic MjQ2MmM5NmItNjQyNy00ZWZiLWFlZDctMTE4ZTIwYzJlOTk3OjhlODdmMGViYzUwZDEwZjFiYzk3MzQzMjlhOTkwMDE3OWI4NGNjZDM5ZTRkMDkyMGI5MDVjYzM1OWNmNmU5NGE2ZTc2MGJiZTNhMDg5MGM3"</code></pre>
 
 <p>
-	cURL Option 2: This cURL command encodes your credentials into Base64.
+	This command takes advantage of curl’s built-in ability to Base-64 encode your credentials, request, and receive your token in a single step. The authorization in your request header will be substituted with "--user {client_id}:{client_secret}"
 </p>
 
 <pre><code>curl -d "" -X POST "https://sandbox.bcda.cms.gov/auth/token" \
-	--user 2462c96b-6427-4efb-aed7-118e20c2e997:8e87f0ebc50d10f1bc9734329a9900179b84ccd39e4d0920b905cc359cf6e94a6e760bbe3a0890c7 \
+	--user <span style="color: #046B99;">{client_id}</span>:<span style="color: #046B99;">{client_secret}</span> \
 	-H "accept: application/json"</code></pre>
 <h4>
 	Access Token Response Example

diff --git a/_includes/build/attribution_status.html b/_includes/build/attribution_status.html
@@ -15,8 +15,8 @@ <h4>Request Headers</h4>
 
 <h4>cURL Command to retrieve the attribution status</h4>
 <pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/attribution_status" \
-    -H "accept: application/json" \
-    -H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "accept: application/json" \
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
 
 <h4>Response Example</h4>
 <pre><code>{

diff --git a/_includes/build/bcda_credentials.html b/_includes/build/bcda_credentials.html
@@ -1,22 +1,28 @@
-<p>
-  In production, BCDA protects its endpoints with OAuth2 access tokens.
-  </p>
+<p>Production credentials authorize your organization's access to the Beneficiary Claims Data API (BCDA). Eligible model entities can manage BCDA credentials by logging into their model-specific system: </p>
+<ul>
+  <li><strong>ACOs in the Medicare Shared Savings Program</strong>: Credential delegates can manage and create credentials from <a href="https://acoms.cms.gov/api-key-mgmt/bcda">ACO Management System (ACO-MS)</a>. </li>
+  <li><strong>REACH ACOs</strong> and <strong>KCEs or KCF practices in the Kidney Care Choices Model</strong>: The following roles can manage and create credentials from <a href="https://4innovation.cms.gov/secure/api-credentials/bcda">4innovation (4i)</a>: <ul>
+      <li>Executive Contact </li>
+      <li>Entity Primary Contact </li>
+      <li>Entity Secondary Contact </li>
+      <li>DUA Requestor </li>
+      <li>DUA Custodian</li>
+    </ul>
+  </li>
+</ul>
+<p>Your registered contact can <a href="https://www.cms.gov/data-research/cms-information-technology/cms-identity-management/help-desk-support">contact the ACO-MS and 4i help desk</a> to assign these roles.</p>
 
-  <div class="ds-c-alert ds-c-alert--hide-icon">
-    <div class="ds-c-alert__body">
-      <h3 class="ds-c-alert__heading">Your credentials are protected data.</h3>
-        <p class="ds-c-alert__text">
-        Please store them safely and securely.	
-      </p>
-	</div>
-  </div>
+<h3 id="create-credentials">Create your credentials</h3>
+<p>BCDA credentials are formatted as a client ID and secret, which your organization will use every time it requests an authentication token. Production credentials are sensitive information and must be stored securely. </p>
+<p>Create BCDA credentials by visiting the <em>API Credentials</em> page in your model-specific system. Choose the <em>BCDA Credentials</em> tab, then select <em>Create New API Credentials</em>. You'll need to provide a public, static IP address for every system, including vendors, that will access the API (up to 8 IP addresses). It may take up to an hour for the allow list to be updated. </p>
 
-<h3>
-Model Entities Gain Access to BCDA through ACO-MS or 4i
-</h3>
+<h3 id="rotate-credentials">Rotate your credentials</h3>
+<p>Your organization's credentials will expire and deactivate after a set period of time. You can rotate BCDA credentials in the <em>API Credentials</em> page to generate a new, active client ID and secret. </p>
+<p>You'll need to rotate credentials every <strong>90 days</strong> in 4i or ACO-MS. Once you choose the <em>BCDA Credentials</em> tab, select the rotate icon under the <em>Actions</em> column. </p>
 
-<p>
- <p><u>ACOs in the Medicare Shared Savings Program:</u> Create and manage your organization's BCDA credentials from the <a href="https://acoms.cms.gov/" rel="noopener">ACO Management System</a>.</p> 
-<p><u>REACH ACOs and KCEs or KCFs in the Kidney Care Choices Model:</u> Create and manage your organization's BCDA credentials from the <a href="https://4innovation.cms.gov/landing" rel="noopener">4i portal</a>.</p>
-<p>When creating new credentials, be prepared to provide the IP address(es) for each system that will make requests to BCDA. It may take up to an hour for the allow list to be updated after the IP address(es) are added.</p>
-</p>
+<h3 id="revoke-credentials">Revoke your credentials</h3>
+<p>You may need to revoke (deactivate) your organization's credentials if they are leaked or compromised. You can create new credentials as a replacement afterward. </p>
+<p>Revoke BCDA credentials in the <em>API Credentials</em> page. Choose the <em>BCDA Credentials</em> tab, then select the delete (x) icon under the <em>Actions</em> column. </p>
+
+<h3 id="credentials-compromised">If your credentials have been compromised</h3>
+<p>Please revoke or rotate your BCDA credentials immediately. Afterward, notify the BCDA team at <a href="mailto:[email protected]">[email protected]</a> to review recent activity. </p>
diff --git a/_includes/build/bcda_v2.html b/_includes/build/bcda_v2.html
@@ -23,15 +23,15 @@ <h2>
                     <pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/Group/all/\$export" \
 -H "accept: application/fhir+json" \
 -H "Prefer: respond-async" \
--H "Authorization: Bearer {access_token}" \
--v</code></pre>
+-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+-i</code></pre>
                 </td>
                 <td>
                     <pre><code>curl -X GET "https://api.bcda.cms.gov/api/v1/Group/all/\$export" \
 -H "accept: application/fhir+json" \
 -H "Prefer: respond-async" \
--H "Authorization: Bearer {access_token}" \
--v</code></pre>
+-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+-i</code></pre>
                 </td>  
             </tr>
         </table>

diff --git a/_includes/build/best_practices_download_speed.html b/_includes/build/best_practices_download_speed.html
@@ -4,15 +4,16 @@ <h3>
   </h3>
 
   <p>
-    Requesting compressed data can help increase your download speed. You can request compressed data files by specifying the `Accept-Encoding: gzip` header in your download requests.
+    Requesting compressed data can help increase your download speed. You can request compressed data files by specifying the `Accept-Encoding: gzip` header in your download requests.  Note that the file downloaded will be a gzip file which you will need to extract into its ndjson format.
   </p>
 
   <H4>
     Sample cURL Command to Download the Data
   </H4>
-  <pre><code>curl "https://sandbox.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson" \
--H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
--H "Accept-Encoding: gzip"
+  <pre><code>curl "<span style="color: #046B99;">{output_url}</span>" \
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	-H "Accept-Encoding: gzip" \
+	--output "your-file-name"
 </code></pre>
 
   <h3>

diff --git a/_includes/build/cancelling_jobs.html b/_includes/build/cancelling_jobs.html
@@ -5,7 +5,7 @@ <h3>Step 1: Obtain an Access Token</h3>
 <h3>Step 2: Send a Request to Cancel a Job</h3>
 
 <h4>Request to Cancel a Job</h4>
-      <pre><code>DELETE /api/v2/jobs/{jobId}</code></pre>
+      <pre><code>DELETE /api/v2/jobs/<span style="color: #046B99;">{job_id}</span></code></pre>
 
 <h4>Request Headers</h4>
 <pre><code>Authorization: Bearer <span style="color: #046B99;">{access_token}</span>

diff --git a/_includes/build/requesting_data_all_three.html b/_includes/build/requesting_data_all_three.html
@@ -32,19 +32,22 @@ <h4>cURL Commands to start a job</h4>
 		<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/Group/all/\$export" \
 	-H "accept: application/fhir+json" \
 	-H "Prefer: respond-async" \
-	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	-i</code></pre>
 	</li>
 	<li>
 		<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/Group/all/\$export?_type=ExplanationOfBenefit,Patient" \
 	-H "accept: application/fhir+json" \
 	-H "Prefer: respond-async" \
-	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	-i</code></pre>
 	</li>
 	<li>
 		<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/Group/all/\$export?_type=Patient" \
 	-H "accept: application/fhir+json" \
 	-H "Prefer: respond-async" \
-	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	-i</code></pre>
 	</li>
 </ol>
 
@@ -55,7 +58,7 @@ <h4>Response Example: Too Many Requests</h4>
 	<pre><code>429 Too Many Requests</code></pre>
 
 <h4>Response Headers</h4>
-	<pre><code>Content-Location: https://api.bcda.cms.gov/api/v2/jobs/42</code></pre>
+	<pre><code>Content-Location: https://api.bcda.cms.gov/api/v2/jobs/<span style="color: #046B99;">{job_id}</span></code></pre>
 
 <h4>Start a Job Explanation</h4>
 	<p>This operation will start a data export job. We have provided three example requests and three example cURL statements to start a job for:</p>
@@ -85,14 +88,14 @@ <h4>Start a Job Explanation</h4>
 <h3 id="checkJob">Step 3: Check the job status</h3>
 
 <h4>Request to check the job status</h4>
-	<pre><code>GET https://api.bcda.cms.gov/api/v2/jobs/42</code></pre>
+	<pre><code>GET https://api.bcda.cms.gov/api/v2/jobs/<span style="color: #046B99;">{job_id}</span></code></pre>
 
 <h4>Request Headers</h4>
 	<pre><code>Authorization: Bearer <span style="color: #046B99;">{access_token}</span>
 Accept: application/fhir+json</code></pre>
 
 <h4>cURL Command to check the job status</h4>
-	<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/jobs/42" \
+	<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/jobs/<span style="color: #046B99;">{job_id}</span>" \
 	-H "accept: application/fhir+json" \
 	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
 
@@ -104,19 +107,19 @@ <h4>Response Example: Completed Job</h4>
   "output": [
     {
       "type": "ExplanationOfBenefit",
-      "url": "https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson"
+      "url": "<span style="color: #046B99;">{output_url}</span>"
     },
     {
       "type": "Coverage",
-      "url": "https://api.bcda.cms.gov/data/42/f76a0b76-48ed-4033-aad9-d3eec37e7e83.ndjson"
+      "url": "<span style="color: #046B99;">{output_url}</span>"
     },
     {
       "type": "Patient",
-      "url": "https://api.bcda.cms.gov/data/42/f92dcf16-63a2-448e-a12a-3bf677f966ed.ndjson"
+      "url": "<span style="color: #046B99;">{output_url}</span>"
     }
   ],
   "error": [],
-  "JobID": 42
+  "JobID": <span style="color: #046B99;">{job_id}</span>
 }
 </code></pre>
 
@@ -132,16 +135,17 @@ <h4>Check the Job Status Explanation</h4>
 <h3 id="downloadData">Step 4: Download the data</h3>
 
 <h4>Request to download the data</h4>
-	<pre><code>GET https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson</code></pre>
+	<pre><code>GET <span style="color: #046B99;">{output_url}</span></code></pre>
 
 <h4>Request Headers</h4>
 	<pre><code>Authorization: Bearer <span style="color: #046B99;">{access_token}</span>
 Accept-Encoding: gzip</code></pre>
 
 <h4>cURL Command to download the data</h4>
-	<pre><code>curl -X GET "https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson" \
+	<pre><code>curl -X GET "<span style="color: #046B99;">{output_url}</span>" \
 	-H "Accept-Encoding: gzip" \
-	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	--output "your-file-name"</code></pre>
 
 <h4>Response Example</h4>
 	<p>
@@ -170,7 +174,7 @@ <h3 class="ds-c-alert__heading"> Files expire after 24 hours.</h3>
 	</div>
 
 	<p>
-		The "Accept-Encoding: gzip" header is optional, but will return a significantly smaller (about 30X smaller) file with a faster download speed. Follow our recommended best practices for <a href="#speeding-up-downloads" class="in-text__link">speeding up downloads</a>.
+		The "Accept-Encoding: gzip" header is optional, but will return a significantly smaller (about 30X smaller) file with a faster download speed. Follow our recommended best practices for <a href="#speeding-up-downloads" class="in-text__link">speeding up downloads</a>.  Note that the file downloaded will be a gzip file which you will need to extract into its ndjson format.
 	</p>
 	<p>
 		The response will be the requested data as FHIR resources in NDJSON format. Each file related to a different resource type will appear separately and labeled as to which resource type it contains. Examples of data from each Resource Type are available in the guide to working with BCDA data.

diff --git a/_includes/build/requesting_data_runouts.html b/_includes/build/requesting_data_runouts.html
@@ -23,27 +23,30 @@ <h4>cURL Commands to start a job</h4>
 		<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/Group/runout/\$export" \
 	-H "accept: application/fhir+json" \
 	-H "Prefer: respond-async" \
-	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	-i</code></pre>
 	</li>
 	<li>
 		<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/Group/runout/\$export?_type=ExplanationOfBenefit,Patient" \
 	-H "accept: application/fhir+json" \
 	-H "Prefer: respond-async" \
-	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	-i</code></pre>
 	</li>
 	<li>
 		<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/Group/runout/\$export?_type=Patient" \
 	-H "accept: application/fhir+json" \
 	-H "Prefer: respond-async" \
-	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	-i</code></pre>
 	</li>
 </ol>
 
 <h4>Response Example: Successful Request</h4>
 	<pre><code>202 Accepted</code></pre>
 
 <h4>Response Headers</h4>
-	<pre><code>Content-Location: https://api.bcda.cms.gov/api/v2/jobs/42</code></pre>
+	<pre><code>Content-Location: https://api.bcda.cms.gov/api/v2/jobs/<span style="color: #046B99;">{job_id}</span></code></pre>
 
 <h4>Start a Job using 'runout' with /Group Explanation</h4>
 	<p>This operation will start a data export job. We have provided three example requests and three example cURL statements to start a job for:</p>

diff --git a/_includes/build/requesting_filtered_data_since_Group.html b/_includes/build/requesting_filtered_data_since_Group.html
@@ -20,7 +20,8 @@ <h4>cURL Command using the _since parameter within the /Group endpoint</h4>
 	<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/Group/all/\$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00" \
 	-H "Accept: application/fhir+json" \
 	-H "Prefer: respond-async" \
-	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	-i</code></pre>
 
 <h4>Response Example: Successful Request</h4>
 <pre><code>202 Accepted</code></pre>
@@ -29,7 +30,7 @@ <h4>Response Example: Too Many Requests</h4>
 <pre><code>429 Too Many Requests</code></pre>
 
 <h4>Response Headers</h4>
-<pre><code>Content-Location: https://api.bcda.cms.gov/api/v2/jobs/42</code></pre>
+<pre><code>Content-Location: https://api.bcda.cms.gov/api/v2/jobs/<span style="color: #046B99;">{job_id}</span></code></pre>
 
 
 <h4>Start a Job using _since within the /Group endpoint Explanation</h4>

diff --git a/_includes/build/requesting_filtered_data_since_Patient.html b/_includes/build/requesting_filtered_data_since_Patient.html
@@ -16,7 +16,8 @@ <h4>cURL Command using the _since parameter within the /Patient endpoint</h4>
 	<pre><code>curl -X GET "https://api.bcda.cms.gov/api/v2/Patient/\$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00" \
 	-H "Accept: application/fhir+json" \
 	-H "Prefer: respond-async" \
-	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>"</code></pre>
+	-H "Authorization: Bearer <span style="color: #046B99;">{access_token}</span>" \
+	-i</code></pre>
 
 <h4>Response Example: Successful Request</h4>
 <pre><code>202 Accepted</code></pre>
@@ -25,7 +26,7 @@ <h4>Response Example: Too Many Requests</h4>
 <pre><code>429 Too Many Requests</code></pre>
 
 <h4>Response Headers</h4>
-<pre><code>Content-Location: https://api.bcda.cms.gov/api/v2/jobs/42</code></pre>
+<pre><code>Content-Location: https://api.bcda.cms.gov/api/v2/jobs/<span style="color: #046B99;">{job_id}</span></code></pre>
 
 
 <h4>Start a Job using _since within the /Patient endpoint Explanation</h4>