feat: unify API Auth docs (Admin, Camunda 8, and Web Modeler APIs)

[pepopowitz]

Description

Part of #4117.

Unifies the content on our various API Authentication docs, so that each API Auth guide contains the following:

• Steps to generate a token, in either a SaaS or self-managed (if available) environment
  • In a SaaS environment, clear description of environment variables to be downloaded when creating a client
• An example auth call, in either a SaaS or self-managed (if available) environment
• An example usage of a generated token, in either a SaaS or self-managed (if available) environment
• A description of token expiration
• (NEW!) Consistent authentication requests between SaaS and self-managed, such that plugging the sample SaaS auth request into an OOTB self-managed environment with the correct variables, will work. (See Incorrect curl command to request bearer token #4092 (comment))

APIs included in this PR

Preview Give feedback

1. Administration API (REST)
2. Camunda 8 API (REST)
3. Web Modeler API (REST)

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]

👋 🤖 🤔 Hello! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.5/.

• docs/apis-tools/camunda-api-rest/camunda-api-rest-authentication.md

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

[pepopowitz]

I'm seeking early feedback on these changes. I may decide to introduce per API incrementally instead of all at once. Some open questions I have:

• Should I do the "deprecated" APIs?
• Should I do previous versions, or only vNext?

[akeller]

• Should I do the "deprecated" APIs?

@pepopowitz see #4071 and the linked Slack convo for updates to the "deprecated APIs"

[pepopowitz]

Note to me (and anyone looking on) that I am ready to acknowledge that the scope of this PR has become too large, and is in danger of living a long time.

Next week I plan to move the tracking of all different auth guides into the linked issue, so that this PR becomes one of many that can be merged incrementally.

[pepopowitz]

Hello friends, this PR is ready for review. When the preview site completes deployment, you can find the updated auth guides at:

• https://preview.docs.camunda.cloud/pr-4078/docs/next/apis-tools/console-sm-api/console-sm-api-authentication/
• https://preview.docs.camunda.cloud/pr-4078/docs/next/apis-tools/camunda-api-rest/camunda-api-rest-authentication/
• https://preview.docs.camunda.cloud/pr-4078/docs/next/apis-tools/web-modeler-api/authentication/

[akeller]

Idea - Could be fancy here and get a variable for the product version 🤷‍♀️

[pepopowitz]

yeah, in general I didn't feel great about these sample API responses. I want to show enough that it's useful, but not so much that people get lost in the details or it's drifting from the real response.

[akeller]

Similar to my comments on #4152, I see it as a bonus to sync the tabs down the page and wasn't sure if we need to note anything about the token expiration.

I didn't mention this outside of my comment about the product version, but I did see a couple of places where we reference a "version" that I worry will be out of date, certainly at minors but potentially at other points. I don't think this is a huge risk because these references are in example json.

All of this to say, ✅ 🚀

[pepopowitz]

This PR is ready for a final review, with all required feedback addressed, and backported to v8.5 (there is no Camunda REST API in version 8.5, so that one was not backported).

[akeller]

No blocking feedback, but this did prompt me to realize we don't have anything in the docs about the Zeebe API moving to the Camunda 8 API. That is out of scope of this PR and I will follow up separately.

[github-actions]

🧹 Preview environment for this PR has been torn down.