RestApiCategories.platformAdministration.desc

platform_administration

2024.03

2023.10

2024.10

2024.11

2024.09

2024.08

2024.12

Manages authorization rules and makes authorization decisions. <details> <summary>Overview:</summary> The Authorization API encapsulates all activities that affect access to system functions and resources. This is a summary of the functional scope of this API: <ul> <li>This API enables authorized users to define access by creating and managing authorization rules and shares.</li> <li>This API enables any principal that has the Secure permission for a particular object to create and manage authorization rules that directly target that object.</li> <li>This API enables any principal that has the Secure permission for a particular object to share that object. If re-sharing is enabled, each share recipient can extend the access that they receive to other users and groups.</li> <li>This API enforces authorization rules by making authorization decisions. Each decision is evaluated for a specific authorization context. The decision process is transparent to end users.</li> <li>This API enables authorized principals to define capabilities that create a role based authorization model.</li> <li>This API explains its authorization decisions by listing all of the rules and shares that contribute to each decision.</li> <li>This API does not manage access to CAS data (caslibs and tables) or CAS actions.</li> </ul> </details> <details> <summary>Security</summary> The Authorization API automatically protects any endpoints of any API that includes dependencies on it. This dependency intercepts calls to the endpoints and builds an authorization context, which is then sent to the Authorization API for evaluation. If the context is granted permission to perform the request action on that endpoint, it returns an HTTP status code of 200 and allows the request to proceed. If the context is prohibited, it returns an HTTP status code of 403 and the request does not continue further. This access is controlled by authorization rules that can be created through bootstrapping, by an administrative user, or by other methods. </details> <details> <summary>Terminology:</summary> <ul> <li>authorization: the process by which a set of principals is evaluated against defined rules and a requested action to determine whether the user can perform the action.</li> <li>authorization context: information about an authorization request (for example, a target URI, the HTTP headers and verb, the requestor's group memberships, or the time of the request).</li> <li>condition: a logical Spring Expression Language (SpEL) expression that evaluates to either true or false. A rule that includes a condition applies only when the condition is true. For example, you can use a condition to make a rule applicable to only to the creator of an object.</li> <li>container: an object that logically contains the URI of one or more member objects. In parent-child relationship between objects, a container represents a parent.</li> <li>decision: a yes or no answer to an authorization request to perform a particular action. Each authorization decision is based on a specific authorization context.</li> <li>permission: a specific action that a rule affects (for example read, update, delete, create, secure, add, or remove).</li> <li>principal: an entity that represents an individual user or a group.</li> <li>rule: an action or set of actions that is either permitted or prohibited for a given principal or set of principals. A rule can include a condition that limits the circumstances under which the rule applies.</li> <li>share: a simplified abstraction of an authorization rule. Each share identifies a target object (resource), a recipient (principal), and a level of access (type). Each share is backed by a corresponding authorization rule. Shares can help users easily make resources available to each other.</li> <li>capability: an association between a principal and a collection of authorization rules, providing the ability to grant role based access control (RBAC) for various actions.</li> </ul> </details> <details> <summary>API Version</summary> This is version 8 of the Authorization API. Changes since version 7 <ul> <li>Added product to capability media types</li> </ul> Changes since version 6 <ul> <li>Added parameterizedLinks for bulk decisions</li> </ul> Changes since version 5 <ul> <li>Added capabilities endpoints</li> </ul> Changes since version 4 <ul> <li>Added the 'enabled' flag to the share media type</li> </ul> Changes since version 3 <ul> <li>Added sharing endpoints</li> <li>Added media type matching flags for explanation endpoints</li> <li>Added includeShares flag for explanation endpoints</li> </ul> </details> <details> <summary>Error Codes</summary> <table> <tr> <th>HTTP Status Code</th> <th>Error Code</th> <th>Description</th> </tr> <tr> <td>400</td> <td>12600</td> <td>The patch 'test' operation failed.</td> </tr> <tr> <td>400</td> <td>12601</td> <td>Attempt to parse expression failed.</td> </tr> <tr> <td>400</td> <td>12700</td> <td>Request cannot be satisfied because sharing is disabled. </td> </tr> <tr> <td>500</td> <td>12800</td> <td>Cannot retrieve group membership info for group. </td> </tr> <tr> <td>500</td> <td>12801</td> <td>Cannot retrieve group membership info for user. </td> </tr> <tr> <td>404</td> <td>12802</td> <td>Capability could not be found.</td> </tr> <tr> <td>400</td> <td>12803</td> <td>Cannot assign principal to capability because principal is not a group.</td> </tr> <tr> <td>400</td> <td>12804</td> <td>Request has mismatched capability name.</td> </tr> <tr> <td>400</td> <td>12805</td> <td>Request includes an unsupported principal type.</td> </tr> <tr> <td>500</td> <td>12806</td> <td>Unable to convert authorization rule to capability.</td> </tr> <tr> <td>404</td> <td>12807</td> <td>Request to remove non-existent authorization rule.</td> </tr> <tr> <td>400</td> <td>12808</td> <td>Request to remove non-existent group.</td> </tr> <tr> <td>500</td> <td>12809</td> <td>Request from an unrecognized user ID.</td> </tr> <tr> <td>403</td> <td>12810</td> <td>Illegal attempt to elevate own permissions.</td> </tr> <tr> <td>415</td> <td>12811</td> <td>The Accept Item header sprecified an unsupported media type.</td> </tr> <tr> <td>428</td> <td>12812</td> <td>The request is missing the If-Match header.</td> </tr> <tr> <td>428</td> <td>12813</td> <td>The ETag is out-of-date.</td> </tr> </table> </details>

Authorization

2023.03

Manages authorization rules and makes authorization decisions. <details> <summary>Overview:</summary> The Authorization API encapsulates all activities that affect access to system functions and resources. This is a summary of the functional scope of this API: <ul> <li>This API enables authorized users to define access by creating and managing authorization rules and shares.</li> <li>This API enables any principal that has the Secure permission for a particular object to create and manage authorization rules that directly target that object.</li> <li>This API enables any principal that has the Secure permission for a particular object to share that object. If re-sharing is enabled, each share recipient can extend the access that they receive to other users and groups.</li> <li>This API enforces authorization rules by making authorization decisions. Each decision is evaluated for a specific authorization context. The decision process is transparent to end users.</li> <li>This API enables authorized principals to define capabilities that create a role based authorization model.</li> <li>This API explains its authorization decisions by listing all of the rules and shares that contribute to each decision.</li> <li>This API does not manage access to CAS data (caslibs and tables) or CAS actions.</li> </ul> </details> <details> <summary>Security</summary> The Authorization API automatically protects any endpoints of any API that includes dependencies on it. This dependency intercepts calls to the endpoints and builds an authorization context, which is then sent to the Authorization API for evaluation. If the context is granted permission to perform the request action on that endpoint, it returns an HTTP status code of 200 and allows the request to proceed. If the context is prohibited, it returns an HTTP status code of 403 and the request does not continue further. This access is controlled by authorization rules that can be created through bootstrapping, by an administrative user, or by other methods. </details> <details> <summary>Terminology:</summary> <ul> <li>authorization: the process by which a set of principals is evaluated against defined rules and a requested action to determine whether the user can perform the action.</li> <li>authorization context: information about an authorization request (for example, a target URI, the HTTP headers and verb, the requestor's group memberships, or the time of the request).</li> <li>condition: a logical Spring Expression Language (SpEL) expression that evaluates to either true or false. A rule that includes a condition applies only when the condition is true. For example, you can use a condition to make a rule applicable to only to the creator of an object.</li> <li>container: an object that logically contains the URI of one or more member objects. In parent-child relationship between objects, a container represents a parent.</li> <li>decision: a yes or no answer to an authorization request to perform a particular action. Each authorization decision is based on a specific authorization context.</li> <li>permission: a specific action that a rule affects (for example read, update, delete, create, secure, add, or remove).</li> <li>principal: an entity that represents an individual user or a group.</li> <li>rule: an action or set of actions that is either permitted or prohibited for a given principal or set of principals. A rule can include a condition that limits the circumstances under which the rule applies.</li> <li>share: a simplified abstraction of an authorization rule. Each share identifies a target object (resource), a recipient (principal), and a level of access (type). Each share is backed by a corresponding authorization rule. Shares can help users easily make resources available to each other.</li> <li>capability: an association between a principal and a collection of authorization rules, providing the ability to grant role based access control (RBAC) for various actions.</li> </ul> </details> <details> <summary>API Version</summary> This is version 6 of the Authorization API. Changes since version 5 <ul> <li>Added capabilities endpoints</li> </ul> Changes since version 4 <ul> <li>Added the 'enabled' flag to the share media type</li> </ul> Changes since version 3 <ul> <li>Added sharing endpoints</li> <li>Added media type matching flags for explanation endpoints</li> <li>Added includeShares flag for explanation endpoints</li> </ul> </details> <details> <summary>Error Codes</summary> <table> <tr> <th>HTTP Status Code</th> <th>Error Code</th> <th>Description</th> </tr> <tr> <td>400</td> <td>12600</td> <td>The patch 'test' operation failed.</td> </tr> <tr> <td>400</td> <td>12601</td> <td>Attempt to parse expression failed.</td> </tr> <tr> <td>400</td> <td>12700</td> <td>Request cannot be satisfied because sharing is disabled. </td> </tr> <tr> <td>500</td> <td>12800</td> <td>Cannot retrieve group membership info for group. </td> </tr> <tr> <td>500</td> <td>12801</td> <td>Cannot retrieve group membership info for user. </td> </tr> <tr> <td>404</td> <td>12802</td> <td>Capability could not be found.</td> </tr> <tr> <td>400</td> <td>12803</td> <td>Cannot assign principal to capability because principal is not a group.</td> </tr> <tr> <td>400</td> <td>12804</td> <td>Request has mismatched capability name.</td> </tr> <tr> <td>400</td> <td>12805</td> <td>Request includes an unsupported principal type.</td> </tr> <tr> <td>500</td> <td>12806</td> <td>Unable to convert authorization rule to capability.</td> </tr> <tr> <td>404</td> <td>12807</td> <td>Request to remove non-existent authorization rule.</td> </tr> <tr> <td>400</td> <td>12808</td> <td>Request to remove non-existent group.</td> </tr> <tr> <td>500</td> <td>12809</td> <td>Request from an unrecognized user ID.</td> </tr> <tr> <td>403</td> <td>12810</td> <td>Illegal attempt to elevate own permissions.</td> </tr> <tr> <td>415</td> <td>12811</td> <td>The Accept Item header sprecified an unsupported media type.</td> </tr> <tr> <td>428</td> <td>12812</td> <td>The request is missing the If-Match header.</td> </tr> <tr> <td>428</td> <td>12813</td> <td>The ETag is out-of-date.</td> </tr> </table> </details>

Viya_35

Manages authorization rules and makes authorization decisions. <details> <summary>Overview:</summary> The Authorization API encapsulates all activities that affect access to system functions and resources. Here is a summary of the functional scope of this API: <ul> <li>This API enables authorized users to define access by creating and managing authorization rules.</li> <li>This API enables any principal that has the Secure permission for a particular object to create and manage authorization rules that directly target that object.</li> <li>This API enforces authorization rules by making authorization decisions. Each decision is evaluated for a specific authorization context. The decision process is transparent to end users.</li> <li>This API explains its authorization decisions by listing all of the rules that contribute to each decision.</li> <li>This API does not manage access to CAS data (caslibs and tables) or CAS actions.</li> </ul> </details> <details> <summary>Security</summary> The Authorization API automatically protects any endpoints of any API that includes dependencies on it. This dependency intercepts calls to the endpoints and builds an authorization context, which is then sent to the Authorization API for evaluation. If the context is granted permission to perform the request action on that endpoint, it returns an HTTP status code of 200 and allows the request to proceed. If the context is prohibited, it returns an HTTP status code of 403 and the request does not continue further. This access is controlled by authorization rules that can be created through bootstrapping, by an administrative user, or by other methods. </details> <details> <summary>Terminology:</summary> <ul> <li>authorization: the process by which a set of principals is evaluated against defined rules and a requested action to determine whether the user can perform the action.</li> <li>authorization context: information about an authorization request (for example, a target URI, the HTTP headers and verb, the requestor's group memberships, or the time of the request).</li> <li>condition: a logical Spring Expression Language (SpEL) expression that evaluates to either true or false. A rule that includes a condition applies only when the condition is true. For example, you can use a condition to make a rule applicable to only to the creator of an object.</li> <li>container: an object that logically contains the URI of one or more member objects. In parent-child relationship between objects, a container represents a parent.</li> <li>decision: a yes or no answer to an authorization request to perform a particular action. Each authorization decision is based on a specific authorization context.</li> <li>permission: a specific action that a rule affects (for example read, update, delete, create, secure, add, or remove).</li> <li>principal: an entity that represents an individual user or a group.</li> <li>rule: an action or set of actions that is either permitted or prohibited for a given principal or set of principals. A rule can include a condition that limits the circumstances under which the rule applies.</li> </ul> </details> <details> <summary>API Version</summary> This is version 3 of the Authorization API. </details> <details> <summary>Error Codes</summary> <table> <tr> <th>HTTP Status Code</th> <th>Error Code</th> <th>Description</th> </tr> <tr> <td>400</td> <td>12600</td> <td>The patch 'test' operation failed.</td> </tr> <tr> <td>400</td> <td>12601</td> <td>Attempt to parse expression failed.</td> </tr> <tr> <td>400</td> <td>12700</td> <td>Request cannot be satisfied because sharing is disabled. </td> </tr> <tr> <td>500</td> <td>12800</td> <td>Cannot retrieve group membership info for group. </td> </tr> <tr> <td>500</td> <td>12801</td> <td>Cannot retrieve group membership info for user. </td> </tr> <tr> <td>400</td> <td>12805</td> <td>Request includes an unsupported principal type.</td> </tr> <tr> <td>404</td> <td>12807</td> <td>Request to remove non-existent authorization rule.</td> </tr> <tr> <td>400</td> <td>12808</td> <td>Request to remove non-existent group.</td> </tr> <tr> <td>500</td> <td>12809</td> <td>Request from an unrecognized user ID.</td> </tr> <tr> <td>403</td> <td>12810</td> <td>Illegal attempt to elevate own permissions.</td> </tr> <tr> <td>415</td> <td>12811</td> <td>The Accept Item header sprecified an unsupported media type.</td> </tr> <tr> <td>428</td> <td>12812</td> <td>The request is missing the If-Match header.</td> </tr> <tr> <td>428</td> <td>12813</td> <td>The ETag is out-of-date.</td> </tr> </table> </details>

Creates a new share that has a system-generated ID.

An example of creating a share that enables another user to read a file that they do not already have access to.

A share that does not have a known ID or sharedBy value. The share has not been saved or the ID is unavailable for some other reason. Compare with SavedShare.

Share

Specifies the format of the incoming share. Supported media types are: <ul> <li>application/json</li> <li>application/vnd.sas.authorization.share+json</li> </ul>

Content-Type

Specifies the desired format of the returned share. Supported media types are: <ul> <li>application/json</li> <li>application/vnd.sas.authorization.share+json</li> </ul>

Accept

Any share that can be referenced by a unique identifier and has been persisted.

Saved Share

Timestamp of when share was last modified.

Last-Modified

Location

ETag

The request was invalid. Returned if the specified share is invalid.

Create a new share

Error

This is a base schema used to define paginated collections of resources. This base schema is extended by other schemas in APIs by adding an 'items' array property. These extensions define the application/vnd.sas.collection media type (version 2)

baseCollection

A link to a related operation or resource.

Link

A link to a related operation or resource with a map of parameter names to values for use in authorization evaluations.

ParameterizedLink

Selection

The response from a pre-flight validation request. For APIs which support validation, the client can run operations (typically on resources in the `/commons/validation`) with `application/vnd.sas.validation+json` as the requested response type (via the `Accept:` request header). The service will validate the request but not execute the request, and return this response to indicate if the request was valid at the time it was made.

Validation Response

property values that specify how sharing is configured. sas.authorization.share.enabled determines whether sharing is enabled at all in the system while sas.authorization.share.reshare.enabled determines whether users are allowed to grant reshare permission on objects.

Share Properties

An authorization rule that does not have a known ID. The rule has not been saved or the ID is unavailable for some other reason. Compare with SavedAuthorizationRule.

Authorization Rule

Any authorization rule that can be referenced by a unique identifier. This can be a savedAuthorizationRule or an unsaved authorization rule that has a client-specified identifier.

Identifiable Authorization Rule

An authorization rule that has a known rule ID and has been persisted.

Saved Authorization Rule

A collection of saved authorization rules.

Resource Collection of Authorization Rules

Principal

A collection of principals (users and/or groups).

Resource Collection of Principals

Contextual information about an action that a principal is attempting. Represented by media type application/vnd.sas.authorization.context+json.

Authorization Context

An authorization context where the permission field is required

Authorization Context Permission Required

Contextual information about an action that a principal is attempting, including one or more links that should be authorized against a supplied permission. Represented by media type application/vnd.sas.authorization.bulk.context+json.
Note: Use of either bulkLinks or parameterizedLinks is required. Use of both is allowed.

Bulk Authorization Context

A map of permissions to link arrays. The keys of this map are the permissions that the link values are authorized for.

Permissions to Links

A map of permissions to parameterized link arrays. The keys of this map are the permissions that the link values are authorized for.  During authorization of the link the parameters will be added to the list of parameters supplied on the context.  The parameters are used in authorization conditional expressions.  If there is a conflict the parameters specified for the link will override.

Permissions to Parameterized Links

A description of the HTTP request that is associated with an authorization request.

Authorization Context Request

A map of relative URI keys to an array of Explanation values. Each explanation in each array explains authorization decisions for one principal.

Explanations

An explanation of access for one principal.

Explanation

An explanation of access for one principal and permission.

Individual Explanation

An explanation of access for one principal and permission. Includes explanations for permissions conveyed by containing objects.

Permission Explanation

Information about the source or cause of the result. Includes a list of applicable rules, indication of whether any of those rules has a condition, and whether the result is direct (a rule directly targets the defined object and is directly assigned to the defined principal).

Factor

Instructions for a set of actions to be performed asynchronously. Consists of a state that describes how the overall asynchronous job is performing and a set of actions to perform on defined rules.

Rule Job

Describes an action to be performed asynchronously on a rule.

Rule Action

An operation to be performed on the defined rule.

Rule Patch Operation

Zero or more links that are to related resources and actions.

Links

Resource Collection of Localized Values

A name-value pair of the form (value: localizedValue).

Localized Value

The result of a bulk authorization request. For each type of link in the request (bulkLinks, parameterizedLinks) two arrays containing the granted and prohibited links will be returned.

Authorized Links

An authorization explanation, using new additional rules that aren't yet persisted in the service

Hypothetical

Resource Collection of Shares

An operation to be performed on the defined share.

Share Patch Operation

Capability summary collection

Capabilties provide an abstraction layer on top of authorization rules, providing the ability to associate users and groups with specific application capabilities, and perform license checks to ensure users are authorized to access various areas of the software

Name	Type	Required	Description
sharedWith	string	true	The principal name of the share recipient.
resourceUri	string	true	A relative URI that represents a resource. All shares must target a resource URI.
name	string	false	The user-friendly name of the shared resource.
sharedWithType	string	true	The type of principal to which the share applies. Allowed values: usergroupauthenticatedUserseveryoneguest
type	string	true	The level of access that the share provides. Allowed values: readreadEditreadSharereadEditShare
enabled	boolean	false	Flag indicating whether the current share is in effect or not. Default: true
version	integer<int32>	false	The version of the share representation. The current representation version is 2.
links	array [Link]	false	Zero or more links that are to related resources and actions.

Status	Meaning	Description
201	Created	A new share was created.	Headers	Schema
400	Bad Request	The request was invalid. Returned if the specified share is invalid.

Create a new share

Request Samples

Response Samples

Header Parameters

Request Body

Responses