Skip to content

Entitlement with REST APIs

Entitlement management is the process that grants, resolves, enforces, revokes and administers fine-grained access privileges.

The WSO2 Identity Server supports REST APIs for entitlement management via the https://{IS_IP}:{IS_PORT}/api/identity/entitlement/decision/ endpoint.

If your WSO2 Identity Server is running on localhost (127.0.0.1) and on the default port, the entitlement endpoint is:

https://localhost:9443/api/identity/entitlement/decision/

Note

The REST APIs are secured with basic authentication. Follow the steps below to add a basic auth header when calling these methods.

  1. Build a string of the form username:password and encode it using Base64.
  2. Define an authorization header with the term Basic, followed by the encoded string. For example, the basic authorization header for admin user with password admin is:

    Authorization: Basic YWRtaW46YWRtaW4=
    

Get API resource list

Description Get the API resource list according to XACML 3.0 specification.
Resource Path /home
HTTP Method GET
Request/Response Format application/json

application/xml

Authentication Basic
Username admin
Password admin
Parameters
Name Located In Description Required Schema
Accept header Request Media Type Yes string
Auth_Type header Authentication Type Yes string
Authorization header Add HTTP Basic Authorization Yes string
Content-type header Response Media Type Yes string
Response
Code Description Schema
200 XACML JSON/XML Response
40010 Error in response
ExceptionBean {
    code:integer
    message:string
}
40020 Request parse exception
ExceptionBean {
    code:integer
    message:string
}



A sample request and response is as follows:

Sample request
Sample Response

Evaluate XACML request

Description Get a response by evaluating the JSON/XML XACML request.
Resource Path /pdp
HTTP Method POST
Request/Response Format

application/json

application/xml

Authentication Basic
Username admin
Password admin
Parameters
Name Located In Description Required Schema
Accept header Request Media Type Yes string
Auth_Type header Authentication Type Yes string
Authorization header Add HTTP Basic Authorization Yes string
Content-type header Response Media Type Yes string
body body XACML JSON/XML Request Yes string
Response
Code Description Schema
200 XACML JSON/XML Response
40010 Error in response
ExceptionBean {
    code:integer
    message:string
}
40020 Request parse exception
ExceptionBean {
    code:integer
    message:string
}



A sample request and response is as follows:

XACML Policy Evaluated
Sample Request
Sample Response

Evaluate XACML request by attributes

Description Get a response by evaluating attributes.
Resource Path /by-attrib
HTTP Method POST
Request/Response Format application/json

application/xml

Authentication Basic
Username admin
Password admin
Parameters
Name Located In Description Required Schema
Accept header Request Media Type Yes string
Auth_Type header Authentication Type Yes string
Authorization header Add HTTP Basic Authorization Yes string
Content-type header Response Media Type Yes string
body body Decision Request Model Yes
DecisionRequestModel {
 
    subject:string
    action:string
    resource:string
    environment:[
            string
    ]
}
Response
Code Description Schema
200 Method call success HomeResponseModel { }
40010 Error in response
ExceptionBean {
    code:integer
    message:string
}
40020 Request parse exception
ExceptionBean {
    code:integer
    message:string
}

A sample request and response are as follows,

A sample request
A sample response

Evaluate XACML request by attributes and receive boolean response

Description Get a boolean response by evaluating attributes.
Resource Path /by-attrib-boolean
HTTP Method POST
Request/Response Format

application/json

application/xml

Authentication Basic
Username admin
Password admin
Parameters
Name Located In Description Required Schema
Accept header Request Media Type Yes string
Auth_Type header Authentication Type Yes string
Authorization header Add HTTP Basic Authorization Yes string
Content-type header Response Media Type Yes string
body body Decision Request Model Yes
DecisionRequestModel {
 
    subject:string
    action:string
    resource:string
    environment:[
            string
    ]
}
Response
Code Description Schema
200 XACML JSON/XML Response
40010 Error in response
ExceptionBean {
    code:integer
    message:string
}
40020 Request parse exception
ExceptionBean {
    code:integer
    message:string
}

A sample request and response are as follows,

A sample request
A sample response
Response: Boolean

Get entitled attributes

Description Get entitled attributes for a given set of parameters.
Resource Path /entitled-attribs
HTTP Method POST
Request/Response Format

application/json

application/xml

Authentication Basic
Username admin
Password admin
Parameters
Name Located In Description Required Schema
Accept header Request Media Type Yes string
Auth_Type header Authentication Type Yes string
Authorization header Add HTTP Basic Authorization Yes string
Content-type header Response Media Type Yes string
body body Decision Request Model Yes
EntitledAttributesRequestModel {
    subjectName:string
    resourceName:string
    subjectId:string
    action:string
    enableChildSearch:boolean
}
Response
Code Description Schema
200 Entitled attributes response
EntitledAttributesResponseModel {
    entitledResultSetDTO:EntitledResultSetDTO {
        entitledAttributesDTOs:[
            EntitledAttributesDTO {
                resourceName:string
                action:string
                environment:string
                allActions:boolean
                allResources:boolean
                attributeDTOs:[
                    AttributeDTO {
                        attributeValue:string
                        attributeDataType:string
                        attributeId:string
                        category:string
                    }
                ]
            }
        ]
        advanceResult:boolean
        message:string
        messageType:string
    }
}
40010 Error in response
ExceptionBean {
    code:integer
    message:string
}
40020 Request parse exception
ExceptionBean {
    code:integer
    message:string
}

A sample request and response are as follows,

A sample request
A sample response

Get all entitlements

Description Get all entitlements for a given set of parameters
Resource Path /entitlements-all
HTTP Method POST
Request/Response Format

application/json

application/xml

Authentication Basic
Username admin
Password admin
Parameters
Name Located In Description Required Schema
Accept header Request Media Type Yes string
Auth_Type header Authentication Type Yes string
Authorization header Add HTTP Basic Authorization Yes string
Content-type header Response Media Type Yes string
body body All Entitlements Model Yes
AllEntitlementsRequestModel {
    identifier:string
    givenAttributes:[
        AttributeDTO {
            attributeValue:string
            attributeDataType:string
            attributeId:string
            category:string
        }
    ]
}
Response
Code Description Schema
200 All entitlements response
AllEntitlementsResponseModel {
    entitledResultSetDTO:EntitledResultSetDTO {
        entitledAttributesDTOs:[
            EntitledAttributesDTO {
                resourceName:string
                action:string
                environment:string
                allActions:boolean
                allResources:boolean
                attributeDTOs:[
                    AttributeDTO {
                        attributeValue:string
                        attributeDataType:string
                        attributeId:string
                        category:string
                    }
                ]
            }
        ]
        advanceResult:boolean
        message:string
        messageType:string
    }
}
40010 Error in response
ExceptionBean {
    code:integer
    message:string
}
40020 Request parse exception
ExceptionBean {
    code:integer
    message:string
}