Entitlements API

Version 28

     

    Overview

     

    Over the years, many customers have expressed interest in programmatically determining the entitlements for content and places within their Jive community. With the new entitlements API (available with the Fall 2014 Jive Cloud release – version 8c4), you can determine the permission settings that a particular user has for a particular piece of content or for a particular place. You can also determine whether there are security rules placed on blogs, groups, or spaces.  The entitlement API conveys both security group permissions and user level permissions to allow for proper interpretation by an external system.

     

    With this information, along with the information that comes from the Analytics API, you can keep track of all activity within a community, and understand the entitlements for all content or places associated with that activity. This combination of information can be essential, for example, when building an enterprise search engine that displays results appropriate to the user performing the search.

     

    Specifically, the Entitlements API provides access to the following details:

     

    1. What entitlements (e.g. view, edit, delete) does a user have for a particular piece of content?
    2. What entitlements (e.g. view, edit, delete, manage) does a user have for a particular place?
    3. What are the security rules for all blogs in the community?
    4. What are the security rules for all groups in the community?
    5. What are the security rules for all spaces in the community?

     

    Content Entitlements for a Particular User

     

    The following endpoints return information about the entitlements of a particular user for the specified content object:

     

    GET EndpointNotes
    /api/core/v3/contents/{contentID}/entitlementsReturns entitlements information about the requesting user for the specified content object. Equivalent to GET /api/core/v3/contents/{contentID}/entitlements/@me.
    /api/core/v3/contents/{contentID}/entitlements/{userID}Returns entitlements information about the specified user (or @me for the requesting user) for the specified content object.

     

    The returned entitlements information is a JSON object with the following structure:

     

    {
      "entitlements" : [ "edit", "view", "delete" ],
      "objectType" : "document",
      "parent" : "http://jive.jiveon.com/api/core/v3/places/{placeID}",
      "type" : "entitlement"
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Where:

    • "entitlements" lists the entitlements for the specified content (e.g. "edit", "view", "delete")
    • "objectType" is the V3 object type (e.g. "document", "discussion")
    • "parent" is the URI of the parent place containing this content object
    • "type" is the object type of this entity (i.e. "entitlement")

     

    Note that entitlements objects are ephemeral and calculated on the fly, so they do not have an "id" themselves.

     

    An HTTP error status is returned in the following situations:

    • 403 (Forbidden) -- Requesting user cannot view the specified content object, so is therefore not allowed to introspect entitlements on that object
    • 404 (Not Found) -- Requested content object does not exist

     

    Place Entitlements for a Particular User

     

    The following endpoints return information about the entitlements of a particular user to a specified place object:

     

    GET EndpointNotes
    /api/core/v3/places/{placeID}/entitlementsReturns entitlements information about the requesting user for the specified place object. Equivalent to GET /api/core/v3/places/{placeID}/entitlements/@me.
    /api/core/v3/places/{placeID}/entitlements/{userID}Returns entitlements information about the specified user (or @me for the requesting user) for the specified place object.

     

    The returned entitlements information is a JSON object similar to that for content objects, but with a couple of extra fields:

     

    {
      "contentTypes" : [ "document", "discussion" ],
      "entitlements" : [ "edit", "view", "delete", "admin" ],
      "objectIType" : "group",
      "parent" : "http://jive.jiveon.com/api/core/v3/places/{placeID}",
      "type" : "entitlement"
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Where:

    • "contentTypes" list the content types the specified user can view, create, or delete, etc. according to the entitlement.
    • "entitlements" lists the entitlements for the specified place (e.g. "edit", "view", "delete", "admin")
    • "objectType" is the V3 object type (e.g. "group", "space", "project")
    • "parent" is the URI of the parent place (if any)
    • "type" is the object type of this entity (i.e. "entitlement")

     

    Note that entitlements objects are ephemeral and calculated on the fly, so they do not have an "id" themselves.

     

    An HTTP error status is returned in the following situations:

    • 403 (Forbidden) -- Requesting user cannot view the specified place object, so is therefore not allowed to introspect entitlements on that object
    • 404 (Not Found) -- Requested place object does not exist

     

    Security Rules Overview

     

    A security rule can be tied to a security group (e.g. administrators) or to specific users. These rules are returned by the API as a list of "AppliedEntitlement" entities. Each entity represents permissions granted (or revoked) for a single user or security group as applied to a single object type. In order to properly interpret the security rules, you should take into account both security group permissions and user level permissions. User permissions always supersede permissions granted by security groups.

     

    The boolean fields of an AppliedEntitlement entity will vary depending on the context and object type: read, edit, create, createPublic (for global groups only), createPrivate (for global groups only), createExternal (for global groups only), admin, comment, rate, vote (for polls only).

     

    Besides the security groups that are manually created, there are two virtual security groups, which have the following URIs:

     

    Security Rules for Blogs

     

    The following endpoint returns information about the security groups and user overrides associated to all blogs:

     

    GET Endpoint
    /api/core/v3/admin/blogs/appliedEntitlements

     

    The response contains a paginated list of AppliedEntitlement entities:

     

    {
      "list": [
        {
          "objectType": "post"
          "read": true,
          "create": false,
          "comment": true,
          "securityGroup": "http://my.jive.com/api/core/v3/admin/securityGroups/123",  
          "type": "appliedEntitlement"
        },
        {
          "objectType": "post"
          "read": true,
          "create": true,
          "comment": true,
          "person": "http://my.jive.com/api/core/v3/people/5678",  
          "type": "appliedEntitlement"
        }
      ],
      "startIndex": 0,
      "itemsPerPage": 10,
      "totalResults": 2
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

     

    Security Rules for Groups

     

    The following endpoint returns information about the security groups and user overrides associated to all social groups:

     

    GET Endpoint
    /api/core/v3/admin/groups/appliedEntitlements

     

    The response contains a paginated list of AppliedEntitlement entities:

     

    {
      "list": [
        {
          "objectType": "group"
          "read": true,
          "createPublic": true,
          "createPrivate": true,
          "createExternal": false,
          "admin": false,
          "securityGroup": "http://my.jive.com/api/core/v3/admin/securityGroups/123",  
          "type": "appliedEntitlement"
        },
        {
          "objectType": "group"
          "read": true,
          "createPublic": true,
          "createPrivate": true,
          "createExternal": true,
          "admin": true,
          "person": "http://my.jive.com/api/core/v3/people/5678",  
          "type": "appliedEntitlement"
        }
      ],
      "startIndex": 0,
      "itemsPerPage": 10,
      "totalResults": 2
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Security Rules for Spaces

     

    The following endpoints return information about the security groups and user overrides associated to a particular space:

     

    GET EndpointNotes
    /api/core/v3/places/{placeID}/appliedEntitlementsReturns the applied entitlements for a particular place.
    /api/core/v3/admin/spaces/appliedEntitlementsReturns the applied entitlements for all spaces.

     

    The response contains a paginated list of AppliedEntitlement entities:

     

    {
      "list": [
        {
          "objectType": "discussion"
          "read": true,
          "edit": false,
          "create": true,
          "admin": false,
          "securityGroup": "http://my.jive.com/api/core/v3/admin/securityGroups/123",  
          "type": "appliedEntitlement"
        },
        {
          "objectType": "discussion"
          "read": true,
          "edit": true,
          "create": true,
          "admin": true,
          "person": "http://my.jive.com/api/core/v3/people/5678",  
          "type": "appliedEntitlement"
        }
      ],
      "startIndex": 0,
      "itemsPerPage": 10,
      "totalResults": 2
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Related REST APIs

     

    The following API endpoints provide access to information indirectly related to entitlements:

     

    GET EndpointNotes
    /api/core/v3/peopleEnumerate (with pagination) through all users of a Jive instance.
    /api/core/v3/securityGroupsEnumerate (with pagination) the defined security groups of a Jive instance, with related endpoints to enumerate or modify security group membership. This API is available to Jive administrators only.
    /api/core/v3/members/places/{placeID}Enumerate (with pagination) the members (owner, member, or both) of a social group, with related endpoints to modify social group membership. This API is available to Jive administrators, or group admin administrators for the modification endpoints.

     

    For More Information

     

    For more information, refer to the Permission Entities section of the REST API.