Skip to content

Website request: Merge permissions into Rest API docs #42738

@rachaelshaw

Description

@rachaelshaw

Goal

User story
As user working on a Fleet API or GitOps integration,
I want to see which roles have access to each API endpoint
so that I can assign the right role to my API-only user.

For help creating a user story, see "Writing a good user story" in the website handbook.

How?

  • Add "bubbles" under each API endpoint in the REST API docs, which are rendered from ((Observer)), ((Observer+)), ((Technician)), ((Maintainer)), ((Admin)), and ((GitOps)) in the markdown. (Example from the Sails.js docs: markdown / page)
  • When an API endpoint has different permissions depending on the global or team scope of the role, add a note to the docs to clarify (or alternatively, we could include icons on each bubble to indicate global/team, but that might be a bit noisy)
  • Update permissions guide to remove the table and point to the API docs instead.
  • Update the user story GitHub issue template ("Permissions" checkbox) to no longer reference updating that guide
  • @rachaelshaw can take the docs portion of this, and can also do a first pass at design before passing to @mike-j-thomas to finalize the styles. @eashaw should be able to copy a lot of the code for parsing the bubbles from the Sails.js website.

Context

Now that we're building #38044, we want to make it easier for users to understand which roles have access to which API endpoint. The existing permissions guide doesn't perfectly map to the API. (Also, merging the permissions docs into the API docs makes it easier to keep up-to-date going forward).

Metadata

Metadata

Assignees

Labels

#g-websiteProduct group: Website (fleetdm.com)

Type

No type

Projects

Status

🐣 In progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions