You signed in with another tab or window.Reload to refresh your session.You signed out in another tab or window.Reload to refresh your session.You switched accounts on another tab or window.Reload to refresh your session.Dismiss alert
## DescriptionAdds a brief section to the API & Session Tokens documentationexplaining API key scopes.## Changes- Added "API Key Scopes" section to`docs/admin/users/sessions-tokens.md`- Includes overview of scope functionality and security benefits- Documents scope format (`resource:action`) and wildcard usage- Provides CLI examples for creating scoped tokens- Lists common scope examples with descriptions## MotivationUsers need documentation on how to create and use scoped API tokens forimproved security by limiting token permissions to only necessaryoperations.## Testing- Reviewed documentation formatting- Verified markdown structure- Confirmed examples are accurate
server flag to set the maximum duration for long-lived tokens in your
82
82
deployment.
83
+
84
+
##API Key Scopes
85
+
86
+
API key scopes allow you to limit the permissions of a token to specific operations. By default, tokens are created with the`all` scope, granting full access to all actions the user can perform. For improved security, you can create tokens with limited scopes that restrict access to only the operations needed.
87
+
88
+
Scopes follow the format`resource:action`, where`resource` is the type of object (like`workspace`,`template`, or`user`) and`action` is the operation (like`read`,`create`,`update`, or`delete`). You can also use wildcards like`workspace:*` to grant all permissions for a specific resource type.
89
+
90
+
###Creating tokens with scopes
91
+
92
+
You can specify scopes when creating a token using the`--scope` flag:
-`workspace:*` - Full workspace access (create, read, update, delete)
106
+
-`template:read` - View template information
107
+
-`api_key:read` - View API keys (useful for automation)
108
+
-`application_connect` - Connect to workspace applications
109
+
110
+
For a complete list of available scopes, see the API reference documentation.
111
+
112
+
###Allow lists (advanced)
113
+
114
+
For additional security, you can combine scopes with allow lists to restrict tokens to specific resources. Allow lists let you limit a token to only interact with particular workspaces, templates, or other resources by their UUID:
**Important:** Allow lists are exclusive - the token can**only** perform actions on resources explicitly listed. In the example above, the token can only read the specified workspace and cannot access any other resources (templates, organizations, other workspaces, etc.). To maintain access to other resources, you must explicitly add them to the allow list:
124
+
125
+
```sh
126
+
# Token that can read one workspace AND access templates and user info