[Docs] Add note on API token organization scope limitations

[Copilot]

Notes for Reviewers

This PR fixes #1386

API tokens are user-scoped, not organization-scoped. Users with membership in multiple organizations need to understand how to explicitly control which organization their API requests operate on.

Changes

• tokens.md: Added info alert explaining tokens are user-scoped with GitHub PAT comparison, referencing the REST API docs for detailed examples
• api-reference.md: New "Specifying Organization Context" section with two approaches:
  • layer5-current-orgid header for per-request org targeting
  • Preferences API for setting default org/workspace

Example

curl -X POST "https://cloud.layer5.io/api/pattern" \
 -H "Authorization: Bearer <Your-Token>" \
 -H "layer5-current-orgid: <Your-Organization-ID>" \
 -H "Content-Type: application/json" \
 -d '{"name": "my-design", "pattern_file": "..."}'

Screenshots

Tokens page

REST API page

Signed commits

• Yes, I signed my commits.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Docs] Add note on limitation of organization scope on API tokens</issue_title>
<issue_description>Topic: Understanding the nuances of Cloud’s REST APIs and API token scope
Purpose: Help users understand the difference between API Tokens and User Sessions. Cloud API Tokens are not org-scoped, but are user-scoped. This is a noteworthy caveat to include in the API documentation, so that users understand how they can explicitly control the use of their API tokens with respect to organizational boundaries.
Applicable to: This note is of import to users who belong to multiple organizations, not to users with membership to only a single org.
Tip: Include ad informational note that readers can relate to: draw upon the similarities of how GitHub Personal Access Tokens work
Example: Include an example of how to create a new design with organization and workspace specified. Through layer5-current-orgid or setting the selectedWorkspace and selectedOrganization preference for user through the preferences api

---

Contributor Guide and Resources

• 📚 Instructions for contributing to documentation
  • Layer5 documentation site and source
• 🎨 Wireframes and designs for Layer5 site in Figma (open invite)
• 🙋🏾🙋🏼 Questions: Layer5 Discussion Forum and Layer5 Community Slack
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Docs] Add note on limitation of organization scope on API tokens #859

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[netlify]

✅ Deploy Preview for bejewelled-pegasus-b0ce81 ready!

Name	Link
🔨 Latest commit	33717dc
🔍 Latest deploy log	https://app.netlify.com/projects/bejewelled-pegasus-b0ce81/deploys/692ec0086368780008c095b9
😎 Deploy Preview	https://deploy-preview-860--bejewelled-pegasus-b0ce81.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[leecalcote]

@aabidsofi19 do you want these two additions swapped with the callout on the API docs and the description in the Organizations docs or is this fine?

[aabidsofi19]

yeah , API docs seems better place .

[aabidsofi19]

@copilot move the actual description of how scope api call to org in rest api docs , and inside the callouts in tokens page refer to them .

[Copilot]

Simplified the tokens.md callout to just reference the REST API docs. The detailed description and examples remain in api-reference.md. See commit 33717dc.