influxdata / influxdata/influxdb
Clarify information about tokens in API docs
- Dominant language
- Rust
- Stars
- 31.7k
- Forks
- 3.7k
- Avg merge
- 13h 37m
- Merged PRs (30d)
- 8
Description
@AlirieGray @brettbuddin @GeorgeMac
cc @stephanie-engel @rhajek
Currently, if folks search for "create a token"
https://docs.influxdata.com/influxdb/v2.0/api/

We see "Create an authorization" 6th in the list. Not all folks are tying together "create a token" and "create an authorization"
- Perhaps we could add a key for the Create an authorization page, so results show both "Create an authorization" and "Create a token-based authorization" or "Create an authorization (token)".
- Under the "Create an authorization" heading, lets add statement directly under heading to clarify: _Create an authorization for a specified organization; this authorization defines permissions and creates a token to use in API requests._
- Next to description: A description of the authorization. Currently, all authorizations (create a token/are token-based?). ....Would folks ever use an existing token to create an authorization?
- Next to permissions: List of permissions for an authorization. Must have at least one permission. Add possible permissions-read/write/all access? Also, what is the "id" under permissions in the Response sample indicate?
- In the request and response samples, under permissions, does the id indicate the user ID and does name indicate the user name?
Contributor guide
Research direction
Start with the InfluxDB API documentation page linked in the issue and inspect the “Create an authorization” heading, search result text, and request/response permission samples. Confirm the intended token terminology and the meanings of permission id and name, then update the heading, description, and examples so users searching for token creation can find and understand the endpoint.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100