Draft an architecture for interacting with project APIs in the docs

[nkuehn]

We are getting more request for interactive and personalized features directly in the platform docs. Examples

• "personalized" code and URL examples for endpoints (incorportating e.g. a region and given project ID)
• directly trying an API call live and seeing the results
• interactive quizzes and tasks that ask the user to do a certain task in their learning project and then verify it's been done right ( @industrian has done a prototype that is quite like)

In any case this means that we need to keep authentication data and e.g. a list of project keys the user used last. It would also require a UI similar to being logged in.

Before going into design and further exploration we would have to do a security and feasibility analysis of how it could be done, esp. how project access credentials can be safely made available in a user session across page views , reloads and evetually also browser sessions.

Generally I can think of three approaches:

• client side only (easiest, direct interaction with the external API, but more susceptible to XSS attacks of any of the sites / microsites livin in the documentation domain)
• client side but with a server side proxy (server in the docs domain). This would allow to store the secret in an Http-only, same domain secure JWE cookie. This would be safer against XSS attacks intending to grab the cookie but client side JS could still trigger calls to the backend API. But it could be filtered server side e.g. for non mutable calls only or other constraints
• leveraging user data storage of an SSO system like Auth0 that would be introduced for other purposes anyways. Could be susceptible to XSS attacks, too?
• sandboxing in an iframe and doing such things in a dedicated subdomain?

ideas only, but we should start the conversation and give it the time it needs.

---

UPDATE: a list of requirements to first decide upon before drafting an architecture.

• user must be personally identifyable in logs (or platform audit log)? e.g. by having to be logged in before being allowed to user interactive features. The platform APIs provide external User ID tracking. Alternatively, if a only client/ID secret is know the client ID is audited but not the actual person.
• ability to configure multiple project / client ID / region configurations across multiple regions? (or just one region and/or project)
• ability to remember access credentials across browser sessions?
• ability to restrict access from stored credentials to readonly (allow only HTTP API GET or graphQL without mutations?)? This would significantly restrict interactions with a lot of APIs but may convey much more trust
• ability to restrict interaction to non-production projects?
• ability to sandbox the secrets / credentials completely from the other javascript in the docs / learning portals? (in the normal click flow, we can't protect anyone from messing up in the browser console)

[nkuehn]

here's a very rough sequence diagram of a proxy based approach (mermaid syntax in the issue here)

option 1: keeping client ID and secret

sequenceDiagram
    actor user as User
    participant browser as Browser
    participant docs as Docs Server
    participant api as Platform API 
    user->>browser: Enter Region, Client Id, project key, secret (credentials)
    browser->>+docs: Please save credentials
    docs->>-browser: OK (data in encrypted JWE, set HttpOnly,SameSite,Secure cookie)
    user->>browser: Please check my task result in the project
    browser->>+docs: GET me the data from the API (includes the JWE cookie)
    docs-->>+api: get a token (if not in the JWE)
    api-->>-docs: here's a token
    docs->>+api: GET data
    api->>-docs: Project data
    docs->-browser: return data (and set JWE including token OR a separate JWE for the token)
    browser->user: Task Verification Result

Loading

But It may be overkill to keep client ID and secret, I guess just keeping the token and optionally a refresh token is the better architecture. They time out naturally and can be invalidated.

option 2: just keeping a token and refresh token

sequenceDiagram
    actor user as User
    participant browser as Browser
    participant docs as Docs Server
    participant api as Platform API 
    user->>browser: Enter Region, Client Id, project key, secret (credentials)
    browser->>+docs: Please get and save a token
    docs-->>docs: maybe do some checks like no production projects, no write permissions...
    docs->>+api: get a token and refresh token
    api->>-docs: here's a token
    docs->>-browser: OK (token in encrypted JWE, set HttpOnly,SameSite,Secure cookie)
    browser->>user: allow selecting that project as your current project connection
    user->>browser: Please check my task result in the project
    browser->>+docs: GET me the data from the API (includes the JWE cookie)
    docs-->>docs: checks like no PII sensitive endpoints, no mutations, ??
    docs->>+api: GET data
    api->>-docs: Project data
    docs->-browser: return data
    browser->user: Task Verification Result

Loading

[nkuehn]

I found a first place that has a similar feature that goes beyond standard https://developers.freshdesk.com/api/ (simply asking to put a project / database key and aPI secret that's it. )

[FFawzy]

Auth0 has a similar feature too .. you can add the Management API Token in the api reference docs page .. and you will be able to try any endpoint against your tenant
https://auth0.com/docs/api/management/v2

[FFawzy]

the above architecture (option 1 or 2) allows us to check any type of mutations that a user executes on their end and then we (docs server) checks if they did it right.

but what about queries ? if we are talking about fetching something .. maybe something like building complex filters and facets.

[nkuehn]

but what about queries ? if we are talking about fetching something .. maybe something like building complex filters and facets.

@FFawzy to be honest I don't really understand this comment. What do you infer from that it would only work for mutations? My "... no mutations???" text in the graph was more a brainstorming idea whether it could make sense to restrict that kind of API access to certain operations. Same for the requirements checklist in the original ticket text - some have question marks as a reminder to discuss the question, that's all.