Open Policy Agent (OPA) REST API

Tools (18)

Extracted live via the executor SDK.

• compileApi.postCompile

  This API endpoint allows you to partially evaluate Rego queries and obtain a simplified version of the policy. The example below assumes that OPA has been given the following policy (use PUT /v1/policies/{path}):

  yaml

  package exampleallow {  input.subject.clearance_level >= data.reports[_].clearance_level}

  Compile API request body so that it contain the following fields:

  Field	Type	Required	Description
  query	string	Yes	The query to partially evaluate and compile.
  input	any	No	The input document to use during partial evaluation (default: undefined).
  unknowns	array[string]	No	The terms to treat as unknown during partial evaluation (default: ["input"]]).

  For example:

  json

  {  "query": "data.example.allow == true",  "input": {    "subject": {      "clearance_level": 4    }  },  "unknowns": [    "data.reports"    ]}

  Partial evaluation

  In some cases, the result of partial valuation is a conclusive, unconditional answer. See the guidance for details.

• configApi.getConfig

  This API endpoint responds with active configuration (result response)

  ---

  Note The credentials field in the services configuration and

  The private_key and key fields in the keys configuration will be omitted from the API response

  ---

• dataApi.deleteDocument

  This API endpoint deletes an existing document from the server

• dataApi.getDocument

  This API endpoint returns the document specified by path.

  The server will return a bad request (400) response if either:

  • The query requires an input document and you do not provide it
  • You provide the input document but the query has already defined it.
• dataApi.getDocumentWithPath

  The server will return a bad request (400) response if either:

  • The query requires an input document and you do not provide it
  • You provided an input document but the query has already defined it.

  If path indexes into an array, the server will attempt to convert the array index to an integer. If the path element cannot be converted to an integer, a not found response (404) will be returned.

• dataApi.getDocumentWithWebHook

  The example given here assumes you have created a policy (with PUT /v1/policies/{path}), such as:

  yaml

  package opa.examplesimport input.example.flagallow_request { flag == true }

  The server will return a not found (404) response if the requested document is missing or undefined.

• dataApi.patchDocument

  This API endpoint updates an existing document on the server by describing the changes required (using JSON patch operations)

• dataApi.putDocument

  If the path does not refer to an existing document (for example us-west/servers), the server will attempt to create all the necessary containing documents.

  This behavior is similar to the Unix command mkdir -p.

• healthApi.getHealth

  This API endpoint verifies that the server is operational.

  The response from the server is either 200 or 500:

  • 200 - OPA service is healthy. If bundles is true, then all configured bundles have been activated. If plugins is true, then all plugins are in an 'OK' state.
  • 500 - OPA service is not healthy. If bundles is true, at least one of configured bundles has not yet been activated. If plugins is true, at least one plugins is in a 'not OK' state.

  ---

  Note This check is only for initial bundle activation. Subsequent downloads will not affect the health check.

  Use the status endpoint (in the (management API)[management.html]) for more fine-grained bundle status monitoring.

  ---

• policyApi.deletePolicyModule

  This API endpoint removes an existing policy module from the server

• policyApi.getPolicies

  This API endpoint responds with a list of all policy modules on the server (result response)

• policyApi.getPolicyModule

  This API endpoint returns the details of the specified policy module ({id})

• policyApi.putPolicyModule
  • If the policy module does not exist, it is created.
  • If the policy module already exists, it is replaced.

  If the policy module isn't correctly defined, a bad request (400) response is returned.

  Example policy module

  yaml

  package opa.examples
  import data.serversimport data.networksimport data.ports
  public_servers[server] {  some k, m  	server := servers[_]  	server.ports[_] == ports[k].id  	ports[k].networks[_] == networks[m].id  	networks[m].public == true}

• queryApi.getQuery

  This API endpoint returns bindings for the variables in the query.

  For more complex JSON queries, use POST /v1/query instead.

• queryApi.postQuery

  This API endpoint returns bindings for the variables in the query.

  For simpler JSON queries, you may use GET /v1/query instead.

• queryApi.postSimpleQuery

  This API queries the document at /data/system/main by default (however, you can configure OPA to use a different path to serve these queries). That document defines the response. For example, use the following in PUT /v1/policies/{path}) to define a rule that will produce a value for the /data/system/main document:

  yaml

  package systemmain = msg {  msg := sprintf("hello, %v", input.user)}

  The server will return a not found (404) response if /data/system/main is undefined.

• openapi.previewSpec

  Preview an OpenAPI document before adding it as a source

• openapi.addSource

  Add an OpenAPI source and register its operations as tools