Identity Cloud: Advanced Policy Manager API v2

Make real-time authorization decisions about who can access protected resources in your website or app.

Learn more:


Overview

The Advanced Policy Manager API allows you to make real-time authorization decisions about who can, and who cannot, access protected resources in your website or in your app.

The Advanced Policy Manager API allows you to make real-time authorization decisions about who and what can access all of the websites, applications, resources, and user data in your ecosystem. The decision engine analyses each incoming access request, gathers the necessary information from user profile data and any relevant external services, and determines whether it should be accepted or denied based on business rules set up in the Advanced Policy Manager.

Accessing the Advanced Policy Manager API Endpoint

Advanced Policy Manager uses the following endpoint construction:

https://{mydomain}.janrainservices.com/apm/{endpoint}

To access your instances of Advanced Policy Manager, replace {mydomain} with your Identity Cloud domain name and {endpoint} with the endpoint name. For example:

https://akamai-documentation.janrainservices.com/apm/governance-engine

Authentication

The Advanced Policy Manager API requires Basic authentication. To create an authentication string, combine your API client ID, a colon (:), and your client secret into a single value. For example, if your client ID is abcdefg and your client secret is hijklmnop, that value would look like this:

abcdefg:hijklmnop

Next, take the newly created string and base64 encode it. For example, on a Mac, you can base encode the string using this command:

echo -n "abcdefg:hijklmnop" | base64

Or, if you’re running Microsoft Windows, you can encode the string by using a Windows PowerShell command similar to this:

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("abcdefg:hijklmn"))

The resulting value (e.g., YWJjZGVmZzpoaWprbG1ub3A=) should be used in your authentication header.

If you are making API calls using Postman, select Basic Auth as your identification type, then use the client ID as the username and the client secret as the password.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Request a policy decision POST /apm/governance_engine

Request a policy decision

Requests a policy decision. Each parameter of the body payload is optional and can be included in the policy decision request when applicable to the context. The available options for each parameter are defined in your Trust Framework and then be applied to policy definitions. The parameters included in a policy decision request are evaluated in real time to determine which policies apply to a user in a particular context.

POST /apm/governance_engine

Content-Type: application/json

Request body:

{
    "domain": "",
    "service": "",
    "identityProvider": "",
    "action": "login",
    "attributes": {
        "requests.type_name": "user",
        "requests.uuid": "d1e8308d-4874-42d7-ab58-17dc2a069fdb",
        "requests.for_client_id": "u5vue8j4rths84y5p6cnyqp6egwx86y7"
    }
}

Status 200 application/json

Object type: PolicyDecision

Download schema: governance-engine.json

Response body:

{
    "id": "7b388ace-50f7-413a-a720-115cc3b8d1fc",
    "deploymentPackageId": "700f3a94-8ed1-4b61-a18f-c82a54c813a1",
    "timestamp": "2018-03-29T15:54:03.613Z",
    "authorised": false,
    "decision": "DENY",
    "statements": [
        {
            "name": "User must provide gender",
            "code": "invalid_gender",
            "payload": "Please provide your gender.",
            "obligatory": true,
            "attributes": {}
        },
        {
            "name": "User must live in whitelisted country",
            "code": "invalid_country",
            "payload": "",
            "obligatory": true,
            "attributes": {
                "settings.whitelisted_countries": "[GB]",
                "entity.primaryAddress.country": ""
            }
        }
    ]
}

Sample curl request

curl -X POST \
  https://apm-admin-documentation.janrainservices.com/api/governance-engine \
  -H 'Content-Type: application/json' \
  -d '{
  "domain": "",
  "service": "",
  "identityProvider": "",
  "action": "login",
  "attributes": {
    "entity.type_name": "user",
    "entity.uuid": "d1e8308d-4874-42d7-ab58-17dc2a069fdb",
    "settings.for_client_id": "u5vue8j4rths84y5p6cnyqp6egwx86y7"
  }
}'

Data

This section provides details for each type of data object the API exchanges.

PolicyDecision

Requests a policy decision from Advanced Policy Management. Policy decisions determine whether or not access is permitted to a protected resource.

Download schema: governance-engine.json

Sample POST response:

{
    "id": "7b388ace-50f7-413a-a720-115cc3b8d1fc",
    "deploymentPackageId": "700f3a94-8ed1-4b61-a18f-c82a54c813a1",
    "timestamp": "2018-03-29T15:54:03.613Z",
    "authorised": false,
    "decision": "DENY",
    "statements": [
        {
            "name": "User must provide gender",
            "code": "invalid_gender",
            "payload": "Please provide your gender.",
            "obligatory": true,
            "attributes": {}
        },
        {
            "name": "User must live in whitelisted country",
            "code": "invalid_country",
            "payload": "",
            "obligatory": true,
            "attributes": {
                "settings.whitelisted_countries": "[GB]",
                "entity.primaryAddress.country": ""
            }
        }
    ]
}

PolicyDecision members

Member Type Description
PolicyDecision: Requests a policy decision from Advanced Policy Management. Policy decisions determine whether or not access is permitted to a protected resource.
authorised Boolean Returns true if the decision is PERMIT. Returns false if the decision is anything except PERMIT.
decision Enumeration Response to the decision request. PERMIT indicates that access should be allowed. DENY indicates that access should not be allowed, or should potentially be allowed if additional conditions are met. NOT_APPLICABLE indicates that no policies could be found that can be applied to the decision request. INDETERMINATE indicates that a policy was applicable based on the information provided in the decision request but that the evaluation could not be resolved to either PERMIT or DENY. This may be due to missing attributes or a service timeout.
deploymentPackageId String Unique identifier of the Advanced Policy Manager deployment package.
id String Unique identifier assigned to the request.
statements PolicyDecision.statements[] Advice associated with the decision request. This advice may be used by the policy enforcement point to determine if any additional steps should be taken.
timestamp String UTC timed when the decision request was submitted.
PolicyDecision.statements[]: Advice associated with the decision request. This advice may be used by the policy enforcement point to determine if any additional steps should be taken.
attributes Object JSON-formatted object containing any attributes that were processed along with the policy decision request.
code String Code identifier assigned to the advice.
name String Name assigned to any advice associated with the decision and the decision request.
obligatory Boolean If true, indicates that the advice must be followed in order for the access request to be allowed.
payload String Optional value that provides a more detailed description of the advice, a set of instructions for the policy enforcement point to follow, or a message for the end user.

Errors

This section provides details on the error responses and HTTP status codes generated by the Advanced Policy Manager API.

Error responses

Error responses for the Advanced Policy Manager API are returned as JSON-formatted objects. For example:

{
    "errors": "Authentication required."
}

Each error response is also assigned an HTTP status code, as shown in the following section.

HTTP status codes

The following table lists the HTTP status codes that you might encounter when using the Advanced Policy Manager API.

Code Description
200 A policy decision was returned.
401 Authentication required: the request was made without credentials or the credentials were invalid.
403 The credentials provided were incorrect for the requested resource.

Last modified: 8/28/2019