# Search API {#search-api}

The Search API defines the message exchange pattern between a client (PEP) and an authorization service (PDP) for returning all of the subjects or objects that match the search criteria.

The Search API is based on the Access Evaluation API, but omits one, and only one, of Subject ID or Object ID.

If the Subject ID is omitted, the search returns all subjects which can perform the specified action on the specified resource.

If the Resource ID is omitted, the search returns all resources on which the specified subject can perform the specified action.

## The Search API Request {#search-request}
The Subject Search request is a 3-tuple constructed of three previously defined entities:

`subject`:
: REQUIRED. The subject (or principal) of type Subject. NOTE that the Subject type is REQUIRED but the Subject ID can be omitted to specify a Subject Search.

`action`:
: REQUIRED. The action (or verb) of type Action.

`resource`:
: REQUIRED. The resource of type Resource. NOTE that the Resource type is REQUIRED but the Resource ID can be omitted to specify a Resource Search.

`page`:
: OPTIONAL. A page token for paged requests.

NOTE: only one of `subject.id` or `resource.id` may be omitted.

### Subject Search Example (non-normative)

The following payload defines a request for the subjects of type `user` that can perform the `can_read` action on the resource of type `account` and ID `123`.

~~~ json
{
"subject": {
"type": "user"
},
"action": {
"name": "can_read",
},
"resource": {
"type": "account",
"id": "123"
}
}
~~~
{: #subject-search-request-example title="Subject Search Example Request"}

### Resource Search Example (non-normative)

The following payload defines a request for the resources of type `account` on which the subject of type `user` and ID `[e-mail]` can perform the `can_read` action.

~~~ json
{
"subject": {
"type": "user",
"id": "[e-mail]"
},
"action": {
"name": "can_read",
},
"resource": {
"type": "account"
}
}
~~~
{: #resource-search-request-example title="Example Request"}

## The Search API Response {#search-response}

The response is a paged array of JSON objects, each specifying a `type` and an `id`.

### Subject Search Response Example

~~~ json
{
"results": [
{
"type": "user",
"id": "[e-mail]"
},
{
"type": "user",
"id": "[e-mail]"
}
],
"page": {
"next_token": ""
}
}
~~~

### Resource Search Response Example

~~~ json
{
"results": [
{
"type": "account",
"id": "123"
},
{
"type": "account",
"id": "456"
}
],
"page": {
"next_token": ""
}
}
~~~

## Paged requests

A response that needs to be split across page boundaries returns a non-empty `page.next_token`.

### Paged Response Example

~~~ json
{
"results": [
{
"type": "user",
"id": "[e-mail]"
},
{
"type": "user",
"id": "[e-mail]"
}
],
"page": {
"next_token": "alsehrq3495u8"
}
}
~~~

To retrieve the next page, provide `page.next_token` in the next request:

### Paged Request Example

~~~ json
{
"subject": {
"type": "user"
},
"action": {
"name": "can_read",
},
"resource": {
"type": "account",
"id": "123"
},
"page": {
"next_token": "alsehrq3495u8"
}
}
~~~

Note: page size is implementation-dependent.