Scope
API to manage scopes.
At an abstract level, a Scope identifies the context in which a permission can apply. Each scope is associated with exactly one externally-defined tenant.
Scopes support the following use cases
- Sub-Tenancy (or tenant group). Each tenant group is a grouping of users and groups within a tenant. Resources are reserved to the tenant group (aka: business group). Access and use of those resources is limited to the members of the tenant group. Users are associated with tenant groups via the assignment of {@link Role}s.
- Access Control Lists (ACLs) - Each scope corresponds to an object controlled by an ACL and each permission corresponds to some operation or set of operations that can be performed on that object.
The following resources are applicable:
- /api/authorization/scopes/types
- /api/authorization/scopes/types/{id}
- /api/authorization/scopes/types/{typeId}/permissions/admin
- /api/authorization/scopes/types/{typeId}/permissions/admin/{adminPermissionId}
- /api/authorization/tenants/{tenantId}/principals/{principalId}/scopes
- /api/authorization/tenants/{tenantId}/principals/{principalId}/scopes/{scopeId}
- /api/authorization/tenants/{tenantId}/scopes
- /api/authorization/tenants/{tenantId}/scopes/{scopeId}
/api/authorization/scopes/types
GET
Returns a page of the resources
Parameters
| name | description | type | default |
|---|---|---|---|
| page | Page Number | query | 1 |
| limit | Number of entries per page | query | 20 |
| $orderby | Multiple comma-separated properties sorted in ascending or descending order | query | |
| $top | Sets the number of returned entries from the top of the response (total number per page in relation to skip) | query | |
| $skip | Sets how many entries you would like to skip | query | |
| $filter | Boolean expression for whether a particular entry should be included in the response | query |
Request Body
| element: | baseUri |
| media types: |
ignore, for internal use only.
Response Body
| element: | Page of scopeType |
| media types: |
a page of the resources
/api/authorization/scopes/types/{id}
PUT
Updates or creates a scope type by its id.
Permissions
| Solution Provider | System Admin | Tenant Manager | User Permissions |
|---|---|---|---|
| AUTHORIZATION_MANAGE_ENTITY |
Parameters
| name | description | type | default |
|---|---|---|---|
| id | the id of the scope type to update or create | path |
Request Body
| element: | scopeType |
| media types: |
the scope type to update or create
Response Body
| element: | scopeType |
| media types: |
the updated scope type
GET
Returns the resource associated with the given id
Parameters
| name | description | type | default |
|---|---|---|---|
| id | the id of the resource | path |
Response Body
| element: | scopeType |
| media types: |
the resource
/api/authorization/scopes/types/{typeId}/permissions/admin
The following operations are supported on this resource:
GET
Retrieves the prerequisite admin permissions associated with the requested scope.
Parameters
| name | description | type | default |
|---|---|---|---|
| page | Page Number | query | 1 |
| limit | Number of entries per page | query | 20 |
| $orderby | Multiple comma-separated properties sorted in ascending or descending order | query | |
| $top | Sets the number of returned entries from the top of the response (total number per page in relation to skip) | query | |
| $skip | Sets how many entries you would like to skip | query | |
| $filter | Boolean expression for whether a particular entry should be included in the response | query | |
| typeId | the id of the scope type | path |
Request Body
| element: | request |
| media types: |
the http request - automatically provided (no need for client to specify)
Response Body
| element: | Page of permission |
| media types: |
Collection of prerequisite admin Permissions associated with the scope type identified by typeId.
PUT
Adds an empty permission to the list of admin permissions of a scope type. Used for testing purposes only.
Parameters
| name | description | type | default |
|---|---|---|---|
| typeId | the id of the scope type | path |
Request Body
| element: | request |
| media types: |
the http request - automatically provided (no need for client to specify)
Response Body
| element: | (custom) |
| media types: |
HTTP headers populated with empty response body.
DELETE
Deletes an empty permission to the list of admin permissions of a scope type. Used for testing purposes only.
Parameters
| name | description | type | default |
|---|---|---|---|
| typeId | the id of the scope type | path |
Request Body
| element: | request |
| media types: |
the http request - automatically provided (no need for client to specify)
Response Body
| element: | (custom) |
| media types: |
HTTP headers populated with empty response body.
/api/authorization/scopes/types/{typeId}/permissions/admin/{adminPermissionId}
PUT
Adds a permission to the list of admin permissions of a scope type.
Permissions
| Solution Provider | System Admin | Tenant Manager | User Permissions |
|---|---|---|---|
| AUTHORIZATION_MANAGE_ENTITY |
Parameters
| name | description | type | default |
|---|---|---|---|
| typeId | the id of the scope type to update | path | |
| adminPermissionId | the id of the permission to add | path |
Request Body
| element: | request |
| media types: |
the http request - automatically provided (no need for client to specify)
Response Body
| element: | (custom) |
| media types: |
HTTP headers populated with empty response body.
DELETE
Removes a permission from the list of admin permissions of a scope type.
Permissions
| Solution Provider | System Admin | Tenant Manager | User Permissions |
|---|---|---|---|
| AUTHORIZATION_MANAGE_ENTITY |
Parameters
| name | description | type | default |
|---|---|---|---|
| typeId | the id of the scope type to update | path | |
| adminPermissionId | the id of the permission to remove | path |
Request Body
| element: | request |
| media types: |
the http request - automatically provided (no need for client to specify)
Response Body
| element: | (custom) |
| media types: |
HTTP headers populated with empty response body.
/api/authorization/tenants/{tenantId}/principals/{principalId}/scopes
GET
Retrieves the scopes a principal is included in system wide.
Parameters
| name | description | type | default |
|---|---|---|---|
| page | Page Number | query | 1 |
| limit | Number of entries per page | query | 20 |
| $orderby | Multiple comma-separated properties sorted in ascending or descending order | query | |
| $top | Sets the number of returned entries from the top of the response (total number per page in relation to skip) | query | |
| $skip | Sets how many entries you would like to skip | query | |
| $filter | Boolean expression for whether a particular entry should be included in the response | query | |
| tenantId | the tenant which the principal belongs to | path | |
| principalId | the id of the principal | path |
Request Body
| element: | baseUri |
| media types: |
not used
Response Body
| element: | Page of scope |
| media types: |
Collection of scopes
/api/authorization/tenants/{tenantId}/principals/{principalId}/scopes/{scopeId}
GET
Retrieves a specific scope a principal is included in system wide.
Parameters
| name | description | type | default |
|---|---|---|---|
| tenantId | the tenant which the principal belongs to | path | |
| principalId | the id of the principal | path | |
| scopeId | the id of the scope | path |
Response Body
| element: | scope |
| media types: |
the scope
/api/authorization/tenants/{tenantId}/scopes
DELETE
Deletes all scopes within the specified tenant.
Parameters
| name | description | type | default |
|---|---|---|---|
| page | Page Number | query | 1 |
| limit | Number of entries per page | query | 20 |
| $orderby | Multiple comma-separated properties sorted in ascending or descending order | query | |
| $top | Sets the number of returned entries from the top of the response (total number per page in relation to skip) | query | |
| $skip | Sets how many entries you would like to skip | query | |
| $filter | Boolean expression for whether a particular entry should be included in the response | query | |
| tenantId | the tenant which the scope belongs to | path |
Status Codes
| HTTP Status Code | Description |
|---|---|
| 204 No Content | No Content |
GET
Retrieves the scopes for the specified tenant.
Parameters
| name | description | type | default |
|---|---|---|---|
| page | Page Number | query | 1 |
| limit | Number of entries per page | query | 20 |
| $orderby | Multiple comma-separated properties sorted in ascending or descending order | query | |
| $top | Sets the number of returned entries from the top of the response (total number per page in relation to skip) | query | |
| $skip | Sets how many entries you would like to skip | query | |
| $filter | Boolean expression for whether a particular entry should be included in the response | query | |
| tenantId | the tenant id to find scopes for | path |
Request Body
| element: | baseUri |
| media types: |
not used
Response Body
| element: | Page of scope |
| media types: |
the scopes for the specified tenant.
/api/authorization/tenants/{tenantId}/scopes/{scopeId}
The following operations are supported on this resource:
DELETE
Deletes the scope.
Parameters
| name | description | type | default |
|---|---|---|---|
| tenantId | the tenant which the scope belongs to | path | |
| scopeId | the id of the scope | path |
Status Codes
| HTTP Status Code | Description |
|---|---|
| 204 No Content | No Content |
GET
Gets a scope by its id.
Parameters
| name | description | type | default |
|---|---|---|---|
| tenantId | the tenant which the scope belongs to | path | |
| scopeId | the id of the scope | path |
Response Body
| element: | scope |
| media types: |
the scope
PUT
Updates or creates a scope by its id.
Parameters
| name | description | type | default |
|---|---|---|---|
| tenantId | the tenant which the scope belongs to | path | |
| scopeId | the id of the scope | path |
Request Body
| element: | scope |
| media types: |
the scope to create or update
Response Body
| element: | scope |
| media types: |
the updated scope