API Documentation

Policy service APIs are consistent with other OSDU APIs in a way that they require Bearer token as authorization header and data partition as data-partition-id header for all the calls. Similarly, user making the call needs to be in a necessary service group to be authorized to make the call. For policy service, the relevant service groups are service.policy.user and service.policy.admin.

All the API's can be found OpenAPI Documentation: https://community.opengroup.org/osdu/platform/security-and-compliance/policy/-/blob/master/docs/openapi.yaml Please note this will not render in gitlab as it's a newer OpenAPI format 3.1.0 and gitlab doesn't yet support that.

Older M18 openapi

Policy APIs for Managing Policies

GET /api/policy/v1/policies

Retrieves all the policies. This API gives the list of all the defined policies and it includes the policy definitions in the raw Rego form. It performs authorization check. The user making the call needs to be either service.policy.user or service.policy.admin in the provided data partition.

curl -X 'GET' \
  '/api/policy/v1/policies' \
  -H 'accept: application/json' \
  -H 'data-partition-id: osdu' \
  -H 'correlation-id: 123' \
  -H 'Authorization: Bearer <TOKEN>'

PUT /api/policy/v1/policies/osdu/partition/{data_partition}/{policy_id}

Create or update a policy with given policy_id. This API will create/update policy definition with provided Rego expression and assign it with provided id. It performs authorization check. The user making the call needs to be service.policy.admin in the provided data partition.

curl -X 'PUT' \
  '/api/policy/v1/policies/osdu/partition/osdu/search.rego' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@search.rego'

GET /api/policy/v1/policies/{policy_id}

Retrieves the policy with the give policy_id. This API returns the definition of the requested policy and it includes the policy definitions in the raw Rego form. It performs authorization check. The user making the call needs to be either service.policy.user or service.policy.admin in the provided data partition.

curl -X 'GET' \
  '/api/policy/v1/policies/osdu/instance/search' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>'

DELETE /api/policy/v1/policies/{policy_id}

Deletes the policy with the give policy_id. The API performs authorization check. The user making the call needs to be a service.policy.admin in the provided data partition.

curl -X 'DELETE' \
  '/api/policy/v1/policies/osdu/partition/osdu/search.rego' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>'

Policy APIs for using policies

POST /api/policy/v1/evaluations/query

Evaluates the provided policy (referenced with policy_id) with the provided input. The payload for the evaluation contains a file with the policy_id and input for evaluation. Input contains the operation, record or list of records, groups that the user is a member of, user attributes that can be used in a policy definition, and legaltags that contain legal attributes for record(s).

For example file data for policy dataauthz.rego: Where XXXX is the data partition and YYYY is a legal tag

{
    "input": {
        "operation": "update",
        "records": [
            {
                "id":"XXXX:test:1.4.1654807204111",
                "kind":"XXXX:bulkupdate:test:1.1.1654807204111",
                "legal":{
                    "legaltags":[
                        "YYYY"
                    ],
                    "otherRelevantDataCountries":["US"],
                    "status":"compliant"
                },
                "acls":{
                    "viewers":["data.default.viewers@XXXX.group"],
                    "owners":["data.default.owners@XXXX.group"]
                }
            }
        ]
    }
}

Curl:

curl -X 'POST' \
  '/api/policy/v1/evaluations/query?policy_id=search2.rego&include_auth=true' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@eval_input_allow.json;type=application/json'

POST /api/policy/v1/translate

Translates the provided policy (referenced in query) with the provided input. The payload for the translate contains a json with the query, input and unknowns for translation. Input contains the operation, and optionally can contain groups that the user is a member of, xuserid to identify the user, as well as the token and data partition.

Also see translate documentation

curl -X 'POST' \
  '/api/policy/v1/translate' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "query": "data.osdu.partition[\"osdu\"].search.allow == true",
        "input": {
            "operation": "view",
            "groups": ["AAA", "BBB"]
        },
        "unknowns": ["input.record"]
}'

Diagnostic Policy APIs

GET /api/policy/v1/info

curl -X 'GET' \
  '/api/policy/v1/info' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123'

GET /api/policy/v1/health

Note some providers may require authentication headers.

curl -X 'GET' \
  'http://localhost:8080/api/policy/v1/health' \
  -H 'accept: application/json' \
  -H 'correlation-id: 124'

GET /api/policy/v1/ready

Note some providers may require authentication headers.

curl -X 'GET' \
  '/api/policy/v1/ready' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123'

GET /diag/policies

Note this API requires ENABLE_DEV_DIAGNOSTICS to be enabled. This should not be enabled in production environments.

curl -X 'GET' \
  '/diag/policies' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>'

GET /api/policy/v1/config

curl -X 'GET' \
  '/api/policy/v1/config' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>'

GET /api/policy/v1/validate

curl -X 'PUT' \
  '/api/policy/v1/validate/dataauthz.rego?template=true' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@dataauthz.rego'

Policy Service Utility APIs

POST /api/policy/v1/compile

The Compile API allows you to partially evaluate Rego queries and obtain a simplified version of the policy.

curl -X 'POST' \
  '/api/policy/v1/compile?metrics=false&instrument=false' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@compile_input1.json;type=application/json'

Metrics

When query parameter metrics=true, the API response will include detailed performance metrics from OPA.

OPA currently supports the following query performance metrics: - timer_rego_input_parse_ns: time taken (in nanoseconds) to parse the input - timer_rego_query_parse_ns: time taken (in nanonseconds) to parse the query. - timer_rego_query_compile_ns: time taken (in nanonseconds) to compile the query. - timer_rego_query_eval_ns: time taken (in nanonseconds) to evaluate the query. - timer_rego_module_parse_ns: time taken (in nanoseconds) to parse the input policy module. - timer_rego_module_compile_ns: time taken (in nanoseconds) to compile the loaded policy modules. - timer_server_handler_ns: time take (in nanoseconds) to handle the API request.

Instrumentation

To enable query instrumentation, specify metrics=true and instrument=true query parameters when executing the API call. Query instrumentation can help diagnose performance problems, however, it can add significant overhead to query evaluation. We recommend leaving query instrumentation off unless you are debugging a performance problem.

GET /api/policy/v1/backup

Experimental Backup API. Allows downloading the bundle for a data partition.

curl -X 'GET' \
  '/api/policy/v1/backup' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>' \
> --output backup-bundle-osdu.tar.gz

GET /api/policy/v1/bootstrap

Experimental Bootstrap API for creating (or reseting) bundle for a data partition.

curl -X 'POST' \
  '/api/policy/v1/bootstrap?force=true' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d ''

GET /api/policy/v1/tenant

Experimental tenant API for retrieving OPA bundle config for a data partition. These details are read from OPA configmap.

curl -X 'GET' \
  'api/policy/v1/tenant?all_data=false' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>'

PUT /api/policy/v1/tenant

Experimental tenant API for updating OPA bundle config for a data partition. Adding new partitions or new details in configuration are not supported in M20.

curl -X 'PUT' \
  '/api/policy/v1/tenant?service=s3&polling_min_delay_seconds=7&polling_max_delay_seconds=14' \
  -H 'accept: application/json' \
  -H 'correlation-id: 123' \
  -H 'data-partition-id: osdu' \
  -H 'Authorization: Bearer <TOKEN>'

Permissions

*Endpoint URL*	*Method*	*Minimum Permissions Required*
/api/policy/v1/policies	GET	service.policy.user
/api/policy/v1/policies/{policy_-_id}	PUT	service.policy.admin
/api/policy/v1/policies/{policy_-_id}	DELETE	service.policy.admin
/api/policy/v1/policies/{policy_-_id}	GET	service.policy.user
/api/policy/v1/evaluations/query	POST	service.policy.user

historical information

Interactive

For interactive swagger I recommend using AdminCLI Browser command

Swagger

$ admincli.py browser /api/policy/v1/docs

Redoc

$ admincli.py browser /api/policy/v1/redoc

OpenAPI json

$ admincli.py browser /api/policy/v1/openapi.json

Response Headers

Policy Service includes some interesting data in it's response headers:

X-Correlation-ID - the provided correlation id or generated one for the request. Added in M19.
X-Process-Time - containing the time in seconds that it took to process the request and generate a response in policy service. This can be extremely useful for helping diagnosing performance issues and removing other infrastructure/internet delays and variance. Time while waiting for other dependent services like OPA and entitlement are included in this elapsed time and are not factored out. This response header was added in M20.
X-SHA-256 - Included in response headers for put /validate/{policy_id}, put /policies/osdu/partition/{data_partition}/{policy_id} and get /policies/osdu/partition/{data_partition}/{policy_id}. This response headers was added in M21 as X-SHA-1 but was later updated for security in M23.
X-Debug-Result response header includes additional debugging information if ENABLE_DEV_DIAGNOSTICS is enabled for get /policies/osdu/partition/{data_partition}/{policy_id}. This may include additional information from OPA.