feat(api): public API plan gating, docs auth, and dashboard snippets (#701)

* fix(automation): align public API plan gating across cloud and self-hosted

Add shared canUsePublicApi helper so cloud allows Early Adopter and
Enterprise while self-hosted requires Enterprise. Update the API key
dashboard page and backend key creation checks to use the same rules.

Co-authored-by: Rotimi Best <rotimi-best@users.noreply.github.com>

* docs(api): document bearer auth on public API reference

Add shared OpenAPI enrichment with bearerAuth security scheme and
authentication instructions. The interactive reference now loads an
enriched spec with Authorize support, and the API guide explains how
to create and use org API keys.

Co-authored-by: Rotimi Best <rotimi-best@users.noreply.github.com>

* feat(dashboard): add API quick-start code snippets on automation page

Mirror the MCP client setup section with cURL, JavaScript, and Python
examples that show how to authenticate public API requests with org keys.

Co-authored-by: Rotimi Best <rotimi-best@users.noreply.github.com>

* ci(openapi): republish spec when public API OpenAPI helpers change

Co-authored-by: Rotimi Best <rotimi-best@users.noreply.github.com>

* feat(dashboard): add Go snippet to API quick-start examples

Co-authored-by: Rotimi Best <rotimi-best@users.noreply.github.com>

* docs(api): use /org/*/api and clarify dashboard key generation path

Co-authored-by: Rotimi Best <rotimi-best@users.noreply.github.com>

* fix(api): escape backticks in OpenAPI description template literal

Greptile flagged that unescaped backticks around * in
PUBLIC_API_OPENAPI_DESCRIPTION evaluated to NaN and dropped auth docs
from the Scalar spec. Also use plan-specific snackbar message on upgrade.

Co-authored-by: Rotimi Best <rotimi-best@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Rotimi Best <rotimi-best@users.noreply.github.com>

apps/docs/content/docs/api.mdx

@@ -4,6 +4,7 @@ description: Use the ClassroomIO public API to manage audience members and cours
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
 
 The ClassroomIO public API is available under:
 
@@ -11,17 +12,53 @@ The ClassroomIO public API is available under:
 https://api.classroomio.com/public-api/v1
 ```
 
-Authentication uses organization-scoped bearer tokens created from `Automation -> API` in the ClassroomIO dashboard.
+Every request must include an organization-scoped API key as a Bearer token.
+
+## Get an API key
+
+Generate keys in the ClassroomIO dashboard as an **organization admin**.
+
+<Steps>
+  <Step>
+    Sign in to [ClassroomIO](https://app.classroomio.com).
+  </Step>
+  <Step>
+    In the org sidebar, open the **Automation** section, then **API**.
+  </Step>
+  <Step>
+    Or go directly to [`/org/*/api`](https://app.classroomio.com/org/*/api). The `*` picks your current organization automatically.
+  </Step>
+  <Step>
+    Click **Generate API key**, name the key, and copy the secret immediately. Keys are shown only once and look like `cio_api_...`.
+  </Step>
+  <Step>
+    Send the key on every request as `Authorization: Bearer cio_api_your_key_here`.
+  </Step>
+</Steps>
+
+<Callout type="warn" title="Paid Access">
+  On ClassroomIO Cloud, API key creation is available on **Early Adopter** and **Enterprise** plans. Self-hosted deployments require **Enterprise**.
+</Callout>
 
 ## Interactive Reference
 
 - [Open the interactive API reference](/docs/api/reference)
 
-## Plan Requirement
+The reference page includes an **Authorize** button. Paste your API key there to try endpoints without writing curl commands.
 
-<Callout type="warn" title="Paid Access">
-  API key creation is available only on Early Adopter and Enterprise plans.
-</Callout>
+### Try requests in the reference UI
+
+1. Open the [interactive API reference](/docs/api/reference).
+2. Click **Authorize** (lock icon).
+3. Select **bearerAuth** and paste your full `cio_api_...` key.
+4. Use **Try it** on any endpoint.
+
+### curl example
+
+```bash
+curl https://api.classroomio.com/public-api/v1/audience \
+  -H "Authorization: Bearer cio_api_your_key_here"
+```
 
 ## Current Surface
 
@@ -50,13 +87,6 @@ Raw OpenAPI JSON:
 - [Public API OpenAPI JSON](https://api.cdn.clsrio.com/openapi/public-api/openapi-latest.json)
 - [Interactive API Reference](/docs/api/reference)
 
-## Authentication Example
-
-```bash
-curl https://api.classroomio.com/public-api/v1/audience \
-  -H "Authorization: Bearer <cio_api_key>"
-```
-
 ## Notes
 
 - API keys are organization-scoped.