Epic: Foundation for Gitpod API (workspace status and auth API's)

[loujaybee]

Context	This epic is the first 🐣 baby-step towards creating a stable external public API for Gitpod by starting with two endpoints which are required to improve the IDE experience on desktop. This epic includes the creation of both: authentication API's and workspace status API's that will take the place of the currently undocumented / not contract-bound internal API's which are being used for auth and workspace status in both JetBrains Gateway and VS Code desktop. Relates to: #7900 (public API roadmap item)
Owner	Product - @loujaybee / Tech - @akosyakov
Value	Having these API's defined will enable Gitpod to have a full desktop IDE experience that does not require the user to go to Gitpod in the browser when accessing Gitpod from desktop. In addition to desktop flows, these API's will be the test-bed for the general design pattern and approach for future (public) API's.
Acceptance Criteria	- Internal API's for auth and workspace are created and documented - Error state handling is established and documented
Growth Area	N/A
Persona(s)	N/A
Hypothesis	N/A
Measurement	N/A
In scope	- Creation of authentication / workspace status API's
Out of scope	- Making the API public - Having public hosted documentation
Complexities	- Client libraries
Latest Update	01.03.2022 - Epic created by @loujaybee, needs review by @akosyakov and co.

[csweichel]

@loujaybee Can we fold this epic into #7900? I.e. why have two separate epics for the same task?

[loujaybee]

👋 @csweichel my understanding was that #7900 was scoped to the full external-facing public API (whereas this epic was originally intended to be scoped to the internal-facing workspace status and auth API's). The work/status reported or discussed here was not necessarily intended for direct consumption from a public audience. I can move the details to the other epic, but I'm conscious of the public-facing view of the API getting polluted with lots of internal discussions 💭

[loujaybee]

Following discussion with @easyCZ, it looks like @gitpod-io/engineering-webapp will pick this one up [1]. I'll leave it up to them if this issue is useful or to close, use the parent roadmap epic (as mentioned above by @csweichel) etc.

Will un-assign from @gitpod-io/engineering-ide

[akosyakov]

After planning of #9136 we discovered more requirements for first iteration:

• We need to invalidate Gitpod token from time to time for that we need API to acquire scopes of the current token.
• We need to present a user identity in an account UI. We need at least id and name of a logged in user.
• We need to track analytics. - Here we are thinking instead of using Public API to talk directly to production untrusted source of Segment.

cc @geropl @easyCZ

[geropl]

Thx @akosyakov, will take these into consideration as well. 🗒️

[geropl]

I'll leave it up to them if this issue is useful or to close, use the parent roadmap epic (as mentioned above by @csweichel) etc.

According to ☝️ I will close this issue after having merged the requirements from Antons comment into the description here.