feat: rewrite Operate API auth guide

[pepopowitz]

Description

Part of #4117.

Rewrites the Operate API Auth guide to align with the specs defined in #4117.

Once approved, I will backport to the current version of the docs also.

SaaS

Self-Managed

Using a token/etc

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support.
• This is already available but undocumented and should be released within a week.
• This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
• This is part of a scheduled alpha or minor. (apply alpha or minor label)
• There is no urgency with this change and can be released at any time.

PR Checklist

• My changes are for an already released minor and are in /versioned_docs directory.
• My changes are for the next minor and are in /docs directory (aka /next/).

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
• My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

[github-actions]

👋 🤖 ✅ Looks like the changes were ported across versions, nice job! 🎉

You can read more about the versioning within our docs in our documentation guidelines.

[akeller]

@pepopowitz can you bring someone in from the Operate team via #ask-operate to review this PR as well?

[akeller]

❓ This is the only API that has docs about cookie auth, which feels suspicious.

[pepopowitz]

My assumption is that this exists for a reason, but I've started a conversation at https://camunda.slack.com/archives/C9B5270DA/p1724352947450009 to hopefully get more clarity.

[mesellings]

NBC: "When" instead of "upon"?

[pepopowitz]

I actually changed this from when to upon, because it felt wrong. You see the values as soon as you're done creating the client, not while you're doing it. I didn't like "after," because it implies that you can go back and get the values later (which you can't do).

Is there a different word to use here?

[mesellings]

"Once"[you have created...] implies straight after
"After" has less emphasis on it being straight after
"When" implies during the process
I guess then it should be after or once, but once is a hurdle in translation as it can also mean numerically. So perhaps we can use "Once" for now, and if translation becomes a thing, we know to revisit this phrasing?

[mesellings]

So it could be: Once you have created the client, capture...

[mesellings]

NBC: Should this be a caution instead of a tip as it is quite important as they cannot get the secret again if they don't copy it now.

[pepopowitz]

I don't feel strongly either way about this; if you do, let me know and I'll adjust.

[mesellings]

NBC: Change passive voice > active voice

You can capture the URL of the Operate REST API when creating an API client. This is represented below....variable. It can...

An easy way to see if you are using passive voice is to see if you can insert "by zombies" and it still makes grammatical sense. For example:

can be captured (by zombies) = passive voice

[mesellings]

Great job @pepopowitz looks really good - concise and clean!

I've left some non-blocking suggestions that you might feel helps, at your discretion if you think they are worth acting on, as some of them are for more of a wider discussion (e.g. using gerunds in headings).

I haven't explicitly approved as I believe an Operate team member needs to perform a review as well?

[christinaausley]

@mesellings Has left a detailed review, largely for active/passive voice, but beyond that, I think this looks great! 👍

[pepopowitz]

This PR is ready for a final review, with all required feedback addressed, and backported to v8.5.

[akeller]

The cleanup here looks fab! Thank you for opening up the conversation about cookie auth. Since that is an ongoing discussion, I wouldn't consider that blocking for this PR.