Docs: Clarify behavior of API keys

[ocdtrekkie]

Work in progress as we need to better define roleAssignment as well. I would prefer this to be like a boxed warning type of thing, but at a glance I don't see any on other pages. A small Note seemed too subtle for this.

[ocdtrekkie]

@orblivion Some initial feedback would be appreciated. Considering the definition of roleAssignment is tucked into a bullet list, I didn't want to get extensive, but I did want to give an example of the roleId pattern that was clear on the counting method of the integer.

[orblivion]

This might be part of your future plan for a big loud warning, but I think that we should make sure that it's clear that the default value is allAccess. We might also want to just specify and explain the allowed values rather than link to the source, since the source doesn't specify what these values mean, and also addPermissions and removePermissions don't even work iirc.

[orblivion]

So maybe list the valid values, put (default) for allAccess, and (recommended) for roleId?

[orblivion]

The nice thing about setting a roleId, and perhaps your reason for recommending it, is that (if memory serves) the roleId per se is what stays connected to the token. The permissions attached to the role can change. So it gives the developer some flexibility for future versions. May be worth mentioning, but I understand if that's too much. In general, the document is getting kind of long.

[orblivion]

I'd worry about newcomers coming in and seeing a long doc and skipping our warnings and going straight to the template parameters. I could think about streamlining the doc, but that's a big investment which is not worth it.

But we pretty much know they won't skip the parameters since at least some of them are required to make it work. So maybe for roleAssignment, implore them to "see Key Security Consideration above" so they know that apiPath won't save them.

Though, if your plan was to put the big scary warning inside "Key Security Consideration" that would probably be fine to do instead.

Also, I wonder if that section could be called "Security and Permissions"? Maybe get a third opinion.

Okay that's all I'll say for now.

[ocdtrekkie]

We discussed on the call that I should clarify the default is effectively allAccess.

[ocdtrekkie]

@orblivion I think we summarized on a call this change would be enough... I really think I shouldn't have left this one unmerged, so putting it back out here!