API Keys: API Documentation (#1158)

krivard · melange396 · commit 6edae2911aec · 2023-05-17T13:19:57.000-04:00
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -1,6 +1,6 @@
 ---
 title: Other Endpoints (COVID-19 and Other Diseases)
-nav_order: 2
+nav_order: 3
 has_children: true
 ---
 
diff --git a/docs/api/api_keys.md b/docs/api/api_keys.md
@@ -0,0 +1,64 @@
+---
+title: API Keys
+nav_order: 1
+has_children: true
+---
+
+# Epidata API Keys
+
+Anyone may access the Epidata API anonymously without providing any personal
+data. Anonymous API access is subject to the following restrictions:
+
+1. public datasets only
+1. rate-limited to 100 requests per hour
+1. only two parameters may have multiple selections
+
+For example, a query for three signals on one date across all counties can be
+submitted anonymously, but a query for three signals on a period of four weeks
+across all counties requires an API key. 
+
+An API key is a pseudonymous access token that grants privileged access to the
+Epidata API. You can request an API key by 
+[registering with us](https://forms.gle/hkBr5SfQgxguAfEt7).
+Privileges of registration may include:
+
+1. restricted-access datasets
+1. no rate limit
+1. no limit on multiple selections
+
+We require an email address for all registrations so that we can contact you to
+resolve problems with excessive or abnormal usage patterns. Any additional
+personal information you provide to us at registration will be much appreciated,
+because it will help us understand what our data is used for and inform our
+plans and priorities, but is voluntary. For more information on how we use and
+store the information you provide us at registration time, see our
+[privacy statement](api/privacy_statement.md).
+
+## Usage
+
+If you choose to [register for an API key](https://forms.gle/hkBr5SfQgxguAfEt7), 
+there are several ways to use your key to authenticate your requests:
+
+### Via request parameter
+
+The request parameter “api_key” can be used to pass the API key to the server.
+Example:
+
+    http://delphi.cmu.edu/epidata/covidcast/meta?api_key=your_api_key_here
+
+### Via Basic Authentication
+
+Another method is using the HTTP basic authorization header with the username
+"epidata" and the API key as the password. Example:
+
+```
+curl -u 'epidata:your_api_key_here' https://delphi.cmu.edu/epidata/covidcast/meta
+```
+
+### Via Bearer Token
+
+Another method is providing the key in a bearer token header. Example:
+
+```
+curl -H 'Authorization: Bearer your_api_key_here' https://delphi.cmu.edu/epidata/covidcast/meta
+```
diff --git a/docs/api/covidcast.md b/docs/api/covidcast.md
@@ -1,7 +1,7 @@
 ---
 title: COVIDcast Main Endpoint
 has_children: true
-nav_order: 1
+nav_order: 2
 ---
 
 # COVIDcast Epidata API
diff --git a/docs/api/privacy_statement.md b/docs/api/privacy_statement.md
@@ -0,0 +1,55 @@
+---
+title: Privacy Statement
+parent: API Keys
+---
+
+# Delphi Privacy Statement
+
+Anyone may access the Epidata API anonymously without providing any personal
+data.
+
+Some features of the API are only available by registering for an API key. We
+require an email address for all registrations so that we can contact you to
+resolve problems with excessive or abnormal usage patterns. Any additional
+personal information you provide to us at registration will be much appreciated,
+because it will help us understand what our data is used for and inform our
+plans and priorities, but is voluntary.
+
+You may also choose to share personal information with us to participate in user
+surveys.
+
+We log information about API traffic including the query parameters, API key,
+and source IP address for each request. We retain these logs for a period of not
+longer than five years. We use this information for the following
+purposes:
+
+* to monitor the responsiveness of the API service
+* to monitor the relative popularity of different data and features, alone and
+  in concert with user survey results
+* to identify excessive or abnormal usage patterns which may harm our system
+
+The logs are only available to members of our operations team, and are expunged
+at or before they reach five years in age.  
+
+If you provide us with your email address, we will only use it to contact you in
+the following scenarios:
+
+* you asked a question in a user survey and we have an answer for you
+* we make improvements or other changes to the Epidata API service
+* the API service experiences an outage
+* your API key is about to expire
+* your API usage becomes excessive or abnormal
+* a voluntary survey of our users, but no more than once every 6 months
+
+We store the mapping from tokens to email addresses in a location separate from
+server logs, using security measures consistent with our internal information
+security practices to help us keep your information secure. We only retrieve
+this mapping to resolve cases of excessive or abnormal usage. We automatically
+disassociate an email address from its API key when the API key has not been
+used for six months, or upon user request. You can request that your
+email address be removed from our records by filling out a 
+[deletion request](https://forms.gle/GucFmZHTMgEFjH197).
+
+For more information, see 
+[Carnegie Mellon’s privacy notice](https://www.cmu.edu/legal/privacy-notice.html).
+Further questions can be directed to delphi-support+privacy@andrew.cmu.edu.
diff --git a/docs/epidata_development.md b/docs/epidata_development.md
@@ -1,6 +1,6 @@
 ---
 title: Epidata API Development Guide
-nav_order: 3
+nav_order: 4
 ---
 
 # Epidata API Development Guide
diff --git a/docs/index.md b/docs/index.md
@@ -14,6 +14,25 @@ group](https://delphi.cmu.edu/). The Epidata API includes:
   quick access to COVID data are available.
 - [Data about other diseases](api/README.md), including influenza, dengue, and
   other diseases tracked by Delphi through various data streams.
+  
+Anyone may access the Epidata API anonymously without providing any personal
+data. Anonymous API access is currently rate-limited and restricted to public
+datasets with a maximum of two of the requested parameters having multiple
+selections (signals, dates, versions, regions, etc).
+
+To request access to restricted datasets, no rate limit, and unlimited multiple
+selections, you can [request a registered API key](https://forms.gle/hkBr5SfQgxguAfEt7).
+
+If you regularly or frequently use our system, please consider using an API key
+even if your usage falls within the anonymous usage limits. API key usage helps
+us understand who and how others are using our Delphi Epidata API, which may in
+turn inform our future research, data partnerships, and funding.
+
+For more information about how we use the data you provide us through your
+registration and API request activity, see our 
+[Privacy Statement](api/privacy_statement.md). At any time, you may submit a 
+[Deletion Request](https://forms.gle/GucFmZHTMgEFjH197) to have us deactivate your key and destroy all
+information associating that key with your identity.
 
 The Delphi group is extremely grateful to Pedrito Maynard-Zhang for all his
 help with the Epidata API [documentation](api/README.md).
diff --git a/docs/new_endpoint_tutorial.md b/docs/new_endpoint_tutorial.md
@@ -1,6 +1,6 @@
 ---
 title: New Endpoint Tutorial
-nav_order: 4
+nav_order: 5
 ---
 
 # Tutorial: Adding a new API endpoint
diff --git a/docs/symptom-survey/index.md b/docs/symptom-survey/index.md
@@ -1,7 +1,7 @@
 ---
 title: COVID-19 Trends and Impact Survey
 has_children: true
-nav_order: 5
+nav_order: 6
 ---
 
 # COVID-19 Trends and Impact Survey
