Auth for Agency and Geography

Author: schnuerle

agency/README.md

@@ -9,10 +9,10 @@ This specification contains a collection of RESTful APIs used to specify the dig
 ## Table of Contents
 
 * [General Information](#general-information)
+  * [Authorization](#authorization)
   * [Versioning](#versioning)
   * [Modes](#modes)
   * [Responses and Error Messages](#responses-and-error-messages)
-  * [Authorization](#authorization)
   * [GBFS](#gbfs)
 * [Vehicles](#vehicles)
   * [Vehicle - Status](#vehicle---status)
@@ -34,6 +34,15 @@ This specification uses data types including timestamps, UUIDs, and vehicle stat
 
 [Top][toc]
 
+
+### Authorization
+
+When making requests, the Agency API expects `provider_id` to be part of the claims in a [JWT](https://jwt.io/) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the Agency. [JSON Web Token](/general-information.md#json-web-tokens) is the recommended format.
+
+General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information.
+
+[Top][toc]
+
 ### Versioning
 
 `Agency` APIs must handle requests for specific versions of the specification from clients.
@@ -54,12 +63,6 @@ See the [Responses][responses] and [Error Messages][error-messages] sections.
 
 [Top][toc]
 
-### Authorization
-
-When making requests, the Agency API expects `provider_id` to be part of the claims in a [JWT](https://jwt.io/) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the Agency.
-
-[Top][toc]
-
 ### GBFS
 
 See the [GBFS Requirement](/README.md#gbfs-requirement) language for more details.

general-information.md

@@ -69,7 +69,7 @@ OAuth 2.0's `client_credentials` grant type (outlined in [RFC6749](https://tools
 
 OAuth 2.0 is an industry standard authorization framework with a variety of existing tooling. The `client_credentials` grant type facilitates generation of tokens that can be used for access by agencies and distributed to data partners.
 
-If an MDS `provider` implements this auth scheme, it **MAY** choose to specify token scopes that define access parameters like allowable time ranges. These guidelines **SHOULD** be encoded into the returned token in a parseable way.
+If an MDS provider implements this auth scheme, it **MAY** choose to specify token scopes that define access parameters like allowable time ranges. These guidelines **SHOULD** be encoded into the returned token in a parseable way.
 
 [Top][toc]
 

geography/README.md

@@ -11,11 +11,11 @@ Geographical data will be stored as GeoJSON and read from either `geographies.js
 ## Table of Contents
 
 * [General Information](#general-information)
+  * [Authorization](#authorization)
   * [Versioning](#versioning)
 * [Distribution](#distribution)
   * [Flat Files](#flat-files)
   * [Response Format](#response-format)
-  * [Authorization](#authorization)
 * [Schema](#schema)
   * [Geography Fields](#geography-fields)
   * [Previous Geographies](#previous-geographies)
@@ -32,6 +32,12 @@ The following information applies to all `geography` API endpoints.
 
 [Top][toc]
 
+### Authorization
+
+This endpoint should be made public. Authorization is not required.
+
+[Top][toc]
+
 ### Versioning
 
 MDS APIs must handle requests for specific versions of the specification from clients.
@@ -72,12 +78,6 @@ See the [Responses][responses] and [Error Messages][error-messages] sections.
 
 [Top][toc]
 
-### Authorization
-
-This endpoint should be made public. Authorization is not required.
-
-[Top][toc]
-
 ## Schema
 
 See the [Endpoints](#endpoints) below for links to their specific JSON Schema documents.

metrics/README.md

@@ -10,10 +10,10 @@ The Metrics API endpoints are intended to be implemented by regulatory agencies,
 
 - [General Information](#general-information)
 - [Implementation](#implementation)
+- [Authorization](#authorization)
 - [Data Requirements](#data-requirements)
 - [Beta Feature](#beta-feature)
 - [Date and Time Format](#date-and-time-format)
-- [Authorization](#authorization)
 - [Data Redaction](#data-redaction)
 - [Metrics Discovery API](#metrics-discovery-api)
 - [Metrics Query API](#metrics-query-api)
@@ -58,6 +58,22 @@ Here are initial design use cases and scenarios for Metrics.
 
 [Top][toc]
 
+## Authorization
+
+### For Agencies hosting the Metrics API
+
+When making requests, the Metrics API expects one of two scopes `metrics:read` or `metrics:read:provider` to be present as part of the `scope` claims in a [JSON Web Token](https://jwt.io/) (JWT) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the agency. See MDS [JSON Web Token](/general-information.md#json-web-tokens) guidance.
+
+If a client has a `metrics:read` scope, they are permitted to read _all_ metrics available via the Metrics API.
+
+If a client has a `metrics:read:provider` scope, they are only permitted to read metrics which pertain to a particular `provider_id` claim in the aforementioned [JWT](https://jwt.io/) `access_token`.
+
+Further scopes and requirements may be added at the discretion of the Agency, depending on their particular access control needs.
+
+General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information.
+
+[Top][toc]
+
 ## Data Requirements
 
 The Metrics API does not replace required MDS Provider and Agency endpoints (e.g., [trips](/provider#trips), [events](/provider#events), [vehicles](/provider#vehicles), etc.) in any way. City regulators use disaggregated data access for policy, data validation, auditing, and operational needs, and the Metrics API is not designed to serve these purposes.
@@ -82,22 +98,6 @@ All interval durations (duration) are [ISO 8601](https://en.wikipedia.org/wiki/I
 
 [Top][toc]
 
-## Authorization
-
-### For Agencies hosting the Metrics API
-
-When making requests, the Metrics API expects one of two scopes `metrics:read` or `metrics:read:provider` to be present as part of the `scope` claims in a [JSON Web Token](https://jwt.io/) (JWT) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the agency. See MDS [JSON Web Token](/general-information.md#json-web-tokens) guidance.
-
-If a client has a `metrics:read` scope, they are permitted to read _all_ metrics available via the Metrics API.
-
-If a client has a `metrics:read:provider` scope, they are only permitted to read metrics which pertain to a particular `provider_id` claim in the aforementioned [JWT](https://jwt.io/) `access_token`.
-
-Further scopes and requirements may be added at the discretion of the Agency, depending on their particular access control needs.
-
-General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information.
-
-[Top][toc]
-
 ## Data Redaction
 
 Some combinations of dimensions, filters, time, and geography may return a small count of trips, which could increase a privacy risk of re-identification. To correct for that, Metrics does not return data below a certain count of results.  This data redaction is called k-anonymity, and the threshold is set at a k-value of 10. For more explanation of this methodology, see our [Data Redaction Guidance document](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Data-Redaction).

policy/README.md

@@ -10,13 +10,13 @@ This specification describes the digital relationship between _mobility as a ser
 
 - [General information](#general-information)
   - [Background](#background)
+  - [Authorization](#authorization)
   - [Update Frequency](#update-frequency)
   - [Updating or Ending Policies](#updating-or-ending-policies)
   - [Versioning](#versioning)
   - [Distribution](#distribution)
 - [REST Endpoints](#rest-endpoints)
   - [Responses and Error Messages](#responses-and-error-messages)
-  - [Authorization](#authorization)
   - [Policies](#policies)
     - [Query Parameters](#query-parameters)
   - [Geographies](#geographies)
@@ -71,6 +71,10 @@ The machine-readable format allows Providers to obtain policies and compute comp
 
 [Top][toc]
 
+### Authorization
+
+This endpoint should be made public. Authorization is not required.
+
 ### Update Frequency
 
 The publishing agency should establish beforehand and communicate to providers how frequently the Policy endpoints are expected to change, how often they should be polled to get the latest information, and expectations around emergency updates.
@@ -127,10 +131,6 @@ The response to a client request must include a valid HTTP status code defined i
 
 See the [Responses section][responses] for information on valid MDS response codes and the [Error Messages section][error-messages] for information on formatting error messages.
 
-### Authorization
-
-This endpoint should be made public. Authorization is not required.
-
 ### Policies
 
 **Endpoint**: `/policies/{id}`  

provider/README.md

@@ -9,6 +9,7 @@ This specification contains a data standard for *mobility as a service* provider
 ## Table of Contents
 
 * [General Information](#general-information)
+  * [Authorization](#authorization)
   * [Versioning](#versioning)
   * [Modes](#modes)
   * [Responses and Error Messages](#responses-and-error-messages)