Clarify that Policy API can require Authorization to access the published material

[pierre-bouffort]

Is your feature request related to a problem? Please describe.

We could clarify the fact that Policy API would sometimes require Authorization to access the policies/geographies published on it.

Describe the solution you'd like

When looking at the documentation of the Policy API, in the Authorization section, we could change the language there to say that the publication with our without Authorization of polices on the Policy API is at-will for the publishing user.

Is this a breaking change

• No, not breaking

Impacted Spec

• policy

Describe alternatives you've considered

N/A

Additional context

We have on multiple occasions at Blue Systems had to publish the policies with Authorized access only to implement some of the use-cases requested by our client cities. So we know this is a minor change for the operators, since they would have credentials for other APIs anyway.

[geneorama]

Capturing some arguments against allowing authorization:

• Providing a provision for authorization risks casting it as "should" have authorization
• Adding authorization adds another layer of maintenance
• Adding authorization adds a barrier for would be civic developers in the public, who (assuming there is a process for obtaining keys) are faced with navigating a system that is opaque and bureaucratic, and may not be supported across administrations

If it's used during development a temporary measure, it is exceptionally risky that the service will never be open:

• A service can't be properly tested in development without authentication because it would require significant changes to the changing the code base
• Funding will almost certainly be reluctant to cover development work to remove authentication once a project is complete

Fundamentally if a service is to be open, then it needs to be designed and tested in the open form.

There ways to address many, if not all, of the justifications for authentication

• Use IP whitelisting for pilots
• Require vendor identification for API calls
• Provide and require use private codes for requests to avoid spoofing, if that is a concern
• Employ security and load balancing systems for the open API just as you would any other open API

[schnuerle]

@pierre-bouffort and others, would like to hear your use cases or reasons why this is needed, based on @geneorama's comments.

[schnuerle]

Merged with #949 but see comment with caveats.