Management API Overview

PolicyServer provides a REST-based API to manage PolicyServer resources including policies, role assignments, permission assignments and tenants. The PolicyServer UI relies on this Management API to supply its features.

Integration Workflow

You can integrate with PolicyServer with your own applications using the Management API.

The PolicyServer Management API is available at your host path with the relative path /management. From this root path, the Management API will return the available PolicyServer resources based on your license and configuration of the Management API host.

Typically the integration workflow follows these steps:

• Request an access token from the PolicyServer token endpoint

• Call the Management API passing the access token and information required for the endpoint being called

Graph Navigation

The Management API uses a graph-like design which reflects the policy, role, permission and assignments hierarchy of the underlying PolicyServer architecture and functionality. The hypermedia design facilitates navigating the graph. To access artifacts in PolicyServer it is expected that the consumer navigate the graph dynamically using the hypermedia links provided. As such, hard coding any consumer against Management API URLs is discouraged as they may change in future.

The following illustrates the response from the /management endpoint returning the top level navigation endpoints. The rel attribute is what expresses the meaning of the endpoint in the graph, while the href returns the endpoint URL. Consuming applications may take a dependency on these rel value to find the associated endpoint URL.

{
    "links": [
    {
        "rel":"license",
        "href":"https://localhost:65471/management/license",
        "name":null
    },
    {
        "rel":"policies",
        "href":"https://localhost:65471/management/policies",
        "name":null
    },
    {
        "rel":"policies",
        "href":"https://localhost:65471/management/policies{?filter,tenant,count,page}",
        "name":"template"
    },
    {
        "rel":"add-policy",
        "href":"https://localhost:65471/management/policies",
        "name":null
    },
    {
        "rel":"delete-subjects",
        "href":"https://localhost:65471/management/subjects/{subjectId}/subject-assignments",
        "name":null
    },
    {
        "rel":"tenants",
        "href":"https://localhost:65471/management/tenants",
        "name":null
    },
    {
        "rel":"tenants",
        "href":"https://localhost:65471/management/tenants{?filter,count,page}",
        "name":"template"
    },
    {
        "rel":"add-tenant",
        "href":"https://localhost:65471/management/tenants",
        "name":null
    },
    {
        "rel":"search",
        "href":"https://localhost:65471/management/search/users",
        "name":"users"
    },
    {
        "rel":"search",
        "href":"https://localhost:65471/management/search/users{?filter,count,page}",
        "name":"users-template"
    },
    {
        "rel":"search",
        "href":"https://localhost:65471/management/search/roles",
        "name":"roles"
    },
    {
        "rel":"search",
        "href":"https://localhost:65471/management/search/roles{?filter,count,page}",
        "name":"roles-template"
    },
    {
        "rel":"validate",
        "href":"https://localhost:65471/management/validate/expression",
        "name":"expression"
    },
    {
        "rel":"authorization",
        "href":"https://localhost:65471/management/authorization",
        "name":null
    }
    ]
}

Notice in the above links, some links are unique and therefore do not have a name, whereas others could have multiples types and therefore do have a name to qualify them. When developing against the hypermedia links, the combination of rel and name values form a contract that your application can depend upon. Conversely, the value and format of the URLs are not contractual and might change in the future.

Integration

You can use the Management API to create custom application integrations with PolicyServer, for example:

• Extending your existing user management applications to manage policies for users and store this information with PolicyServer

• Pre-loading the PolicyServer database with tenants, roles, permissions or policy hierarchies rather than manually creating these items via the PolicyServer UI

The Management API requires a valid token issued by the PolicyServer token server (i.e. authority or issuer). Any custom integrations must request a token prior to calling the API. See the PolicyServer Samples for an example of this.

For more information see Management API Endpoints

HTTP Responses

The following HTTP responses should be considered when making requests to any of the PolicyServer APIs.

Status	Description
200	The request was successful. Where applicable the documentation will provide payload details.
201	The resource was created. A location header is returned for the new resource.
400	A bad request was submitted, possibly incorrect parameters or payload.
403	The request was forbidden, likely due to an invalid token.
404	The resource was not found or does not exist. Possibly a bad request path.
500	An unexpected server error occurred. The logs should produce the reason for this, and we’d love to fix it.

Bad Request (HTTP Status Code 400) Error Payload

When a request is made to PolicyServer and the response status code is 400 Bad Request, then a standard error payload is returned. The errors contained in the payload are expected to be safe for end users to view (since they might contain validation error messages).

Response

Data returned:

{
   "errors": ["The Policy name is required."]
}

Versioning

The PolicyServer APIs are versioned. By default when making requests to any endpoint the latest version of the API will be used. To request a specific version of the API, a version=<number> query parameter should be passed to the endpoint being requested.

To determine the current version of the API, make a HTTP GET request to the /management endpoint and inspect the returned version value in the response data. For example:

{
    "data": {
        "version": 1
    }
}