Skip to content

Commit 1a592fd

Browse files
Copilotaabidsofi19
Copilot
and
aabidsofi19
committed
Add documentation for API token organization scope limitations
Co-authored-by: aabidsofi19 <[email protected]>
1 parent b9daddb commit 1a592fd

File tree

2 files changed

+146
-0
lines changed

2 files changed

+146
-0
lines changed

‎content/en/cloud/reference/api-reference.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,142 @@ curl <protocol>://<Layer5-cloud-hostname>/<API> \
2525
- Replace `<API>` with the API endpoint you want to access. For example, `/api/identity/users/profile`.
2626
- Replace `<token>` with the security token you generated.
2727

28+
## Specifying Organization Context
29+
30+
{{< alert type="info" title="API Tokens are User-Scoped" >}}
31+
Layer5 Cloud API tokens are scoped to your user account, not to a specific organization. This means a single API token provides access to all organizations you are a member of. For users who belong to multiple organizations, you need to explicitly specify which organization your API requests should operate on.
32+
33+
This is similar to how [GitHub Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) work, where a single token grants access to all repositories and organizations the user has access to.
34+
{{< /alert >}}
35+
36+
There are two ways to control the organization context for your API requests:
37+
38+
### Using the `layer5-current-orgid` Header
39+
40+
Include the `layer5-current-orgid` header with your organization's ID to specify the target organization for a request:
41+
42+
{{< tabpane >}}
43+
{{< tab header="cURL" >}}
44+
curl -X POST "https://cloud.layer5.io/api/pattern" \
45+
-H "Authorization: Bearer <Your-Token>" \
46+
-H "layer5-current-orgid: <Your-Organization-ID>" \
47+
-H "Content-Type: application/json" \
48+
-d '{"name": "my-design", "pattern_file": "..."}'
49+
50+
{{< /tab >}}
51+
52+
{{< tab header="JavaScript" >}}
53+
54+
const token = "Your-Token";
55+
const orgId = "Your-Organization-ID";
56+
57+
async function createDesign() {
58+
const res = await fetch("https://cloud.layer5.io/api/pattern", {
59+
method: "POST",
60+
headers: {
61+
Authorization: `Bearer ${token}`,
62+
"layer5-current-orgid": orgId,
63+
"Content-Type": "application/json",
64+
},
65+
body: JSON.stringify({
66+
name: "my-design",
67+
pattern_file: "...",
68+
}),
69+
});
70+
const data = await res.json();
71+
console.log(data);
72+
}
73+
74+
createDesign();
75+
76+
{{< /tab >}}
77+
78+
{{< tab header="Python" >}}
79+
80+
import requests
81+
import json
82+
83+
url = "https://cloud.layer5.io/api/pattern"
84+
headers = {
85+
"Authorization": "Bearer <Your-Token>",
86+
"layer5-current-orgid": "<Your-Organization-ID>",
87+
"Content-Type": "application/json"
88+
}
89+
payload = {
90+
"name": "my-design",
91+
"pattern_file": "..."
92+
}
93+
94+
res = requests.post(url, headers=headers, data=json.dumps(payload))
95+
print(res.json())
96+
97+
{{< /tab >}}
98+
99+
{{< /tabpane >}}
100+
101+
### Setting Organization and Workspace Preferences
102+
103+
Alternatively, you can set your default organization and workspace using the Preferences API. This sets your user preferences so that subsequent API requests will use the specified organization and workspace context:
104+
105+
{{< tabpane >}}
106+
{{< tab header="cURL" >}}
107+
# Set organization and workspace preferences
108+
curl -X PUT "https://cloud.layer5.io/api/identity/users/preferences" \
109+
-H "Authorization: Bearer <Your-Token>" \
110+
-H "Content-Type: application/json" \
111+
-d '{
112+
"selectedOrganization": "<Your-Organization-ID>",
113+
"selectedWorkspace": "<Your-Workspace-ID>"
114+
}'
115+
116+
{{< /tab >}}
117+
118+
{{< tab header="JavaScript" >}}
119+
120+
const token = "Your-Token";
121+
122+
async function setPreferences() {
123+
const res = await fetch("https://cloud.layer5.io/api/identity/users/preferences", {
124+
method: "PUT",
125+
headers: {
126+
Authorization: `Bearer ${token}`,
127+
"Content-Type": "application/json",
128+
},
129+
body: JSON.stringify({
130+
selectedOrganization: "<Your-Organization-ID>",
131+
selectedWorkspace: "<Your-Workspace-ID>",
132+
}),
133+
});
134+
const data = await res.json();
135+
console.log(data);
136+
}
137+
138+
setPreferences();
139+
140+
{{< /tab >}}
141+
142+
{{< tab header="Python" >}}
143+
144+
import requests
145+
import json
146+
147+
url = "https://cloud.layer5.io/api/identity/users/preferences"
148+
headers = {
149+
"Authorization": "Bearer <Your-Token>",
150+
"Content-Type": "application/json"
151+
}
152+
payload = {
153+
"selectedOrganization": "<Your-Organization-ID>",
154+
"selectedWorkspace": "<Your-Workspace-ID>"
155+
}
156+
157+
res = requests.put(url, headers=headers, data=json.dumps(payload))
158+
print(res.json())
159+
160+
{{< /tab >}}
161+
162+
{{< /tabpane >}}
163+
28164
## All API Endpoints
29165

30166
{{< alert type="info" >}}

‎content/en/cloud/security/tokens.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,16 @@ Layer5 Cloud REST API uses [OAuth 2.0](https://oauth.net/2/) for authentication
1515

1616
Access tokens are opaque tokens that conform to the OAuth 2.0 framework. They contain authorization information, but not identity information. They are used to authenticate and provide authorization information to Layer5 APIs. Access tokens are associated with a user account. They have an unlimited lifetime and can be revoked at any time.
1717

18+
{{< alert type="info" title="API Tokens are User-Scoped, Not Organization-Scoped" >}}
19+
Layer5 Cloud API tokens are scoped to your user account, not to a specific organization. This means a single API token provides access to all organizations you are a member of, similar to how [GitHub Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) work. For users who belong to multiple organizations, this is an important consideration when using API tokens for automation or integrations.
20+
21+
To explicitly control which organization your API requests operate on, you can:
22+
- Use the `layer5-current-orgid` header to specify the target organization for each request
23+
- Set your `selectedOrganization` and `selectedWorkspace` preferences via the [Preferences API](/cloud/reference/api-reference/#specifying-organization-context)
24+
25+
See [Specifying Organization Context](/cloud/reference/api-reference/#specifying-organization-context) in the REST API documentation for detailed examples.
26+
{{< /alert >}}
27+
1828
## Creating tokens
1929

2030
You can create a token for your user account at any time. Tokens never expire, but can be revoked. You can also give the token a descriptive label. This label will be shown in the list of tokens on your user account's security tokens page.

0 commit comments

Comments
 (0)